MAGICGrants/getmonero.dev
1
0
Fork 0
mirror of https://github.com/MAGICGrants/getmonero.dev.git synced 2026-01-07 20:13:53 -05:00
Code Issues Packages Projects Releases Wiki Activity

Redirect pages to docs.getmonero.org

Browse Source
This commit is contained in:
Justin Ehrenhofer
2025-08-11 15:13:42 -05:00
parent bf3fd10fd7
commit 8e16042f8e
72 changed files with 199 additions and 6134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
README.md
View File

@@ -1,100 +1,3 @@
# GetMonero.dev
## About
GetMonero.dev attempts to organize basic technical knowledge on Monero in one place. It is a continuation of [the MoneroDocs repo](https://github.com/monerodocs/md).
While technical explanations are out there, knowledge is scattered through reddit posts, git comments, stack exchange answers, chat logs and the source code. This makes it hard to find complete and up-to-date explanations on advanced topics.
The goal is to educate and onboard power users faster.
## Contributing
Contributing is easy and much appreciated! You can contribute in the markdown format by opening a pull request.
The documentation is organized into various folders (skip over the ones that start with an underscore `_`). Each of these folders contain markdown files.
Each folder needs a markdown file in it with the same name, acting as the parent. Children markdown files can be added to the folder. Please follow another example folder for the correct header content or follow the [Just the Docs documentation](https://just-the-docs.com/).
You will need to make a new branch to propose changes with a pull request.
If you do not know how to make a pull request, please create a GitHub issue with the page content you would like to add or modify, and someone will help you out with the changes.
## Images
Images should be placed under a folder in `/images` using the same folder name for the relevant markdown file.
When linking images, follow a format like this:
`[![Image name](/images/image.jpg){:width="32%"}](/images/image.jpg)`
This will format the image to 1/3 of the width of the screen, and it will allow a user to click on the image to get a full-screen view. This makes sense for some vertical images.
In select circumstances (such as short, wide images), it's better to make the image full-width. To do this, delete `{:width="32%"}` from the formatting above.
Please use `avif`, `webp`, or `svg` images instead of `jpg` or `png` images. `webp` and `avif` are supported by all modern browsers.
## Videos
Videos should have an accompanying image, and the link should go to the external video. For example:
`[![Image name](https://img.youtube.com/vi/<insert-youtube-video-id-here>/maxresdefault.jpg){:width="100%"}](https://youtube.com/watch?v=<insert-youtube-video-id-here>)`
At the time of writing, `maxresdefault.jpg` returns a 1280x720 image.
## Running the Docs Locally
It can be helpful to inspect your local changes to the documentation before contributing back to the original repository, or if you wish to view the documentation offline.
### Debian 12
You need to install following packages:
```bash
sudo apt install ruby-full bundler
```
First, using GitHub's web user interface, fork the original repository to your own GitHub account. Then, clone your repository to your local computer, make sure to change `${YOUR-USERNAME}` with your GitHub account name:
```bash
git clone https://github.com/${YOUR-USERNAME}/getmonero.dev.git
cd getmonero.dev
```
Now set your git config for your local repo:
```bash
git config user.name '${YOUR-USERNAME}'
git config user.email '${YOUR-EMAIL}'
```
If you don't want to specify your email address, simply enter a dummy one, like `user@host.localdomain`. Note: in order to further protect your email privacy while using GitHub, review your GitHub account settings.
Create a new branch and checkout to that branch. Make sure the `<branch-name>` reflects your local changes to the documentation:
```bash
git checkout -b <branch-name>
```
Now compile the documentation. Create a local directory for storing the compilation dependencies:
```bash
mkdir -p vendor/bundle
bundle config set path vendor/bundle
```
Now install the dependencies:
```bash
bundle install
```
Once the installation is complete, you can run your Jekyll project using:
```bash
bundle exec jekyll serve
```
You can visit `http://127.0.0.1:4000` on your web browser and browse the getmonero.dev documentation. The changes to your local branch will appear in real time as you are doing the edits.
Once you are done with your changes to your local copy of the documentation, you should push your changes to your GitHub repository. Then, using GitHub's web user interface, you should create a pull request from your branch to the getmonero.dev main branch.
This repository is deprecated. Please contribute to https://docs.getmonero.org (https://github.com/monero-project/monero-docs)

6
_redirects/cold-storage/offline-transaction-signing Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /accepting-monero/overview
redirect_to: https://docs.getmonero.org/cold-storage/offline-transaction-signing/
---

6
_redirects/cryptography/asymmetric/edwards25519 Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/asymmetric/edwards25519
redirect_to: https://docs.getmonero.org/cryptography/asymmetric/edwards25519/
---

6
_redirects/cryptography/asymmetric/introduction Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/asymmetric/introduction
redirect_to: https://docs.getmonero.org/cryptography/asymmetric/introduction/
---

6
_redirects/cryptography/asymmetric/key-image Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/asymmetric/key-image
redirect_to: https://docs.getmonero.org/cryptography/asymmetric/key-image/
---

6
_redirects/cryptography/asymmetric/private-key Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/asymmetric/private-key
redirect_to: https://docs.getmonero.org/cryptography/asymmetric/private-key/
---

6
_redirects/cryptography/asymmetric/public-key Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/asymmetric/public-key
redirect_to: https://docs.getmonero.org/cryptography/asymmetric/public-key/
---

6
_redirects/cryptography/base58 Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/base58
redirect_to: https://docs.getmonero.org/cryptography/base58/
---

6
_redirects/cryptography/introduction Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/introduction
redirect_to: https://docs.getmonero.org/cryptography/introduction/
---

6
_redirects/cryptography/keccak-256 Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /cryptography/keccak-256
redirect_to: https://docs.getmonero.org/cryptography/keccak-256/
---

0
cryptography/prng.md → _redirects/cryptography/prng
View File

6
_redirects/index Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /
redirect_to: https://docs.getmonero.org
---

6
_redirects/infrastructure/infrastructure Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /infrastructure/infrastructure
redirect_to: https://docs.getmonero.org/infrastructure/infrastructure/
---

6
_redirects/infrastructure/monero-pulse Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /infrastructure/monero-pulse
redirect_to: https://docs.getmonero.org/infrastructure/monero-pulse/
---

6
_redirects/infrastructure/networks Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /infrastructure/networks
redirect_to: https://docs.getmonero.org/infrastructure/networks/
---

6
_redirects/infrastructure/tor-onion-p2p-seed-nodes Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /infrastructure/tor-onion-p2p-seed-nodes
redirect_to: https://docs.getmonero.org
---

6
_redirects/interacting/download-monero-binaries Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/download-monero-binaries
redirect_to: https://docs.getmonero.org/interacting/download-monero-binaries/
---

0
interacting/monero-blockchain-export.md → _redirects/interacting/monero-blockchain-export
View File

6
_redirects/interacting/monero-blockchain-import Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/monero-blockchain-import
redirect_to: https://docs.getmonero.org/interacting/monero-blockchain-import/
---

0
interacting/monero-config-file.md → _redirects/interacting/monero-config-file
View File

6
_redirects/interacting/monero-wallet-cli Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/monero-wallet-cli
redirect_to: https://docs.getmonero.org/interacting/monero-wallet-cli/
---

6
_redirects/interacting/monero-wallet-gui Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/monero-wallet-gui
redirect_to: https://docs.getmonero.org/interacting/monero-wallet-gui/
---

6
_redirects/interacting/monero-wallet-rpc Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/monero-wallet-rpc
redirect_to: https://docs.getmonero.org/interacting/monero-wallet-rpc/
---

6
_redirects/interacting/monerod Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/monerod
redirect_to: https://docs.getmonero.org/interacting/monerod/
---

6
_redirects/interacting/overview Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/overview
redirect_to: https://docs.getmonero.org/interacting/overview/
---

6
_redirects/interacting/verify-monero-binaries Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /interacting/verify-monero-binaries
redirect_to: https://docs.getmonero.org/interacting/verify-monero-binaries/
---

6
_redirects/multisignature Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /multisignature
redirect_to: https://docs.getmonero.org/multisignature/
---

0
proof-of-work/cryptonight.md → _redirects/proof-of-work/cryptonight
View File

6
_redirects/proof-of-work/pow-in-cryptocurrencies Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /proof-of-work/pow-in-cryptocurrencies
redirect_to: https://docs.getmonero.org/proof-of-work/pow-in-cryptocurrencies/
---

6
_redirects/proof-of-work/proof-of-work Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /proof-of-work/proof-of-work
redirect_to: https://docs.getmonero.org/proof-of-work/proof-of-work/
---

6
_redirects/proof-of-work/random-x Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /proof-of-work/random-x
redirect_to: https://docs.getmonero.org/proof-of-work/random-x/
---

6
_redirects/proof-of-work/what-is-pow Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /proof-of-work/what-is-pow
redirect_to: https://docs.getmonero.org/proof-of-work/what-is-pow/
---

0
public-address/integrated-address.md → _redirects/public-address/integrated-address
View File

6
_redirects/public-address/main-address Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /public-address/main-address
redirect_to: https://docs.getmonero.org/public-address/main-address/
---

6
_redirects/public-address/public-address Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /public-address/public-address
redirect_to: https://docs.getmonero.org/public-address/public-address/
---

6
_redirects/public-address/standard-address Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /public-address/standard-address
redirect_to: https://docs.getmonero.org/public-address/standard-address/
---

6
_redirects/public-address/subaddress Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /public-address/subaddress
redirect_to: https://docs.getmonero.org/public-address/subaddress/
---

6
_redirects/running-node/open-node-tor-onion Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /running-node/open-node-tor-onion
redirect_to: https://docs.getmonero.org/running-node/monerod-tori2p/
---

6
_redirects/technical-specs Normal file
View File

@@ -0,0 +1,6 @@
---
layout: redirected
sitemap: false
permalink: /technical-specs
redirect_to: https://docs.getmonero.org/technical-specs/
---

251
cold-storage/offline-transaction-signing.md
View File

@@ -1,251 +0,0 @@
---
title: Offline Transaction Signing
has_children: false
---
# Offline Transaction Signing
{: .warning}
> This is **NOT** necessarily the recommended cold storage setup, due to high complexity, large room for errors and employing a general purpose computer for transaction signing (even if offline).
>
> Published for educational purposes only to understand "what would it take to sign offline".
>
> It is generally better to use a hardware wallet like Trezor or Ledger.
>
> Opinions may vary.
{: note}
This is a guest tutorial contributed by [crocket](https://github.com/crocket).
Offline transaction signing involves:
* Creating an unsigned transaction on an online, view-only wallet
* Moving the unsigned transaction to an offline machine
* Signing the unsigned transaction on an offline machine
* Moving the signed transaction back to online, view-only wallet
* Broadcasting the transaction
## Creating a new offline wallet
Constructing a new offline wallet is done by executing:
```
monero-wallet-cli --generate-new-wallet /path/to/wallet-file
```
on an offline machine. Record the seed on paper by executing `seed` on the offline wallet.
## Creating a new offline wallet with seed offset passphrase
Seed and seed offset passphrase combine to create a new seed. You can store seed
and seed offset passphrase in separate places so that a thief can't steal your
fund without stealing seed and seed offset passphrase. I recommend 6 to 8
(english) words as a seed offset passphrase as one english word has 11 bits of
entropy on average and 8 words have 88 bits of entropy. With seed passphrase,
you can also create decoy wallets that contain a little bit of money and can
protect you from torturers or blackmailers who demand money from you.
If you want to create an offline wallet with seed and seed passphrase,
create an offline wallet, record the seed on paper, delete the wallet file,
generate seed offset passphrase, record seed offset passphrase on paper, and
execute
```
monero-wallet-cli --generate-new-wallet /path/to/wallet-file \
---restore-deterministic-wallet
```
to restore from seed and seed offset passphrase. When you restore from seed, you
can enter seed offset passphrase.
Generate seed offset passphrase on an offline machine or with diceware because
humans are bad at creating random passphrases.
If you want to reconstruct an existing offline wallet that received or sent
transactions, you need extra steps. Refer to `Restoring offline wallet`.
## Creating a new view-only wallet
To create a view-only wallet, copy primary address and secret view key from an
offline wallet to an online machine where a view-only wallet is going to be
created. You can get primary address by executing `address` on an offline wallet
and secret view key by executing `viewkey` on the offline wallet.
You can use a microSD card and two USB microSD card readers to exchange data
between an offline wallet and a view-only wallet. You can also use a USB flash
drive.
To create a view-only wallet on an online machine, execute
```
monero-wallet-cli --generate-from-view-key /path/to/wallet-file \
--daemon-address remote-node-address:port
```
If you want to reconstruct an existing view-only wallet that received or sent
transactions, refer to `Restoring view-only wallet`.
## Launching offline wallet
Execute
```
monero-wallet-cli --wallet-file /path/to/wallet-file
```
## Launching a view-only wallet
Execute
```
monero-wallet-cli --wallet-file /path/to/wallet-file \
--daemon-address remote-node-address:port
```
It's safe to sync your wallet over clearnet. If you want to broadcast a
transaction without revealing your IP address, execute
```
monero-wallet-cli --wallet-file /path/to/wallet-file \
--daemon-address tor-or-i2p-remote-node-address:port \
--proxy 127.0.0.1:tor-or-i2p-port
```
Synchronizing wallet over clearnet is a lot faster than doing it on tor or i2p.
Thus, consider synchronizing over clearnet even if you broadcast transactions
over tor or i2p.
## Offline transaction signing
Execute any wallet command that transfers monero to any address. For example,
```
transfer xmr-address amount-of-xmr-to-send
```
Any transfer command on a view-only wallet creates `unsigned_monero_tx` in the
current working directory.
Move `unsigned_monero_tx` to an offline machine that has an offline wallet.
Execute
```
sign_transfer
```
on the offline wallet in the directory with `unsigned_monero_tx`.
`signed_monero_tx` file is created in the current working directory. Move
`signed_monero_tx` to the online machine with a view-only wallet. In the
directory with `signed_monero_tx`, launch the view-only wallet, and execute
```
submit_transfer
```
Because a view-only wallet doesn't have key images, it can't see outgoing
transactions. To make a view-only wallet see outgoing transactions, it has
to export new outputs created by `submit_transfer` to an offline wallet which
creates key images out of new outputs.
Execute
```
export_outputs outputs
```
on a view-only wallet. Move `outputs` file to the offline machine with an offline
wallet. Launch the offline wallet, and execute
```
import_outputs /path/to/outputs
```
Export key images derived from new outputs by executing
```
export_key_images key_images
```
on an offline wallet. Move `key_images` file to the machine with a view-only
wallet. Launch the view-only wallet, and execute
```
import_key_images /path/to/key_images
```
## Updating wallet software on an offline signing machine
When you update an offline machine with offline wallets, you can't just
connect the machine to the internet and update wallet software because
doing so exposes offline wallets to the internet.
Instead, boot OS installation media, wipe filesystems, and then connect
to the internet, and install everything from scratch again.
If your root filesystem is encrypted, OS installation media can connect
to the internet from the beginning because encrypted data are safe until
they are decrypted.
## Restoring offline wallet
After updating wallet software on an offline signing machine by wiping it out
and reinstalling everything, you have to restore offline wallet.
Restore an offline wallet from seed (and seed offset passphrase) by executing
```
monero-wallet-cli --generate-new-wallet wallet-file --restore-deterministic-wallet
```
The new offline wallet can't sign new transactions because it doesn't have
all trasaction outputs that precede a new unsigned transaction. Thus, it first
has to import all outputs from a view-only wallet.
On a view-only wallet that was derived from the offline wallet, execute
```
export_outputs all all_outputs
```
`all` is important because `export_outputs` exports only new outputs that weren't
exported before, but
```
export_outputs all
```
exports all outputs. Move `all_outputs` file to the offline machine with the
offline wallet. Execute
```
import_outputs /path/to/all_outputs
```
on the new offline wallet.
## Restoring view-only wallet
If you reconstruct view-only wallet, because it doesn't have key images,
it can't see outgoing transactions. If it can't see outgoing transactions,
it reports wrong account balances. Thus, it has to import all key images
from its corresponding offline wallet.
On the offline wallet, execute
```
export_key_images all all_key_images
```
`export_key_images` doesn't work because it exports only new key images that
weren't exported before.
```
export_key_images all
```
exports all key images. Move `all_key_images` file to the machine with the
view-only wallet. Execute
```
import_key_images /path/to/all_key_images
```

84
cryptography/asymmetric/edwards25519.md
View File

@@ -1,84 +0,0 @@
---
title: Edwards25519 Elliptic Curve
parent: Asymmetric Cryptography in Monero
grand_parent: Cryptography in Monero
---
# Edwards25519 Elliptic Curve
{: .warning}
Author is nowhere close to being a cryptographer. Be sceptical on accuracy.
{: .note}
This article is only about the underlying curve. Public key derivation and signing algorithm will be treated separately.
Monero employs edwards25519 elliptic curve as a basis for its key pair generation.
The curve comes from the Ed25519 signature scheme. While Monero takes the curve unchanged, it does not exactly follow rest of the Ed25519.
The edwards25519 curve is [birationally equivalent to Curve25519](https://tools.ietf.org/html/rfc7748#section-4.1).
## Definition
This is the standard edwards25519 curve definition, no Monero specific stuff here,
except the naming convention. The convention comes from the CryptoNote
whitepaper and is widely used in Monero literature.
### Curve equation
−x^2 + y^2 = 1 − (121665/121666) * x^2 * y^2
Note:
* curve is in two dimensions (nothing fancy, like all the curves is high school)
* curve is mirrored below y axis due to `y^2` part of the equation (not a polynomial)
### Base point: `G`
The base point is a specific point on the curve. It is used
as a basis for further calculations. It is an arbitrary choice
by the curve authors, just to standardize the scheme.
Note that it is enough to specify the y value and the sign of the x value.
That's because the specific x can be calculated from the curve equation.
G = (x, 4/5) # take the point with the positive x
# The hex representation of the base point
5866666666666666666666666666666666666666666666666666666666666666
### Prime order of the base point: `l`
In layment terms, the "canvas" where the curve is drawn is assumed
to have a finite "resolution", so point coordinates must "wrap around"
at some point. This is achieved by modulo the `l` value (lowercase L).
In other words, the `l` defines the maximum scalar we can use.
l = 2^252 + 27742317777372353535851937790883648493
# => 7237005577332262213973186563042994240857116359379907606001950938285454250989
The `l` is a prime number specified by the curve authors.
In practice this is the private key's strength.
### Total number of points on the curve
The total number of points on the curve is also a prime number:
q = 2^255 - 19
In practice not all points are "useful" and so the private key strength is limited to `l` describe above.
## Implementation
Monero uses (apparently modified) Ref10 implementation by Daniel J. Bernstein.
## Reference
* [A (Relatively Easy To Understand) Primer on Elliptic Curve Cryptography](https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/)
* [RFC 8032 defining EdDSA](https://tools.ietf.org/html/rfc8032)
* [Understanding Monero Cryptography](https://steemit.com/monero/@luigi1111/understanding-monero-cryptography-privacy-introduction) - excellent writeup by Luigi
* [StackOverflow answer](https://monero.stackexchange.com/questions/2290/why-how-does-monero-generate-public-ed25519-keys-without-using-the-standard-publ)
* [Python implementation](https://github.com/monero-project/mininero/blob/master/ed25519.py) - not the reference one but easier to understand
* [Encoding point to hex](https://monero.stackexchange.com/questions/6050/what-is-the-base-point-g-from-the-whitepaper-and-how-is-it-represented-as-a)
* [EdDSA on Wikipedia](https://en.wikipedia.org/wiki/EdDSA)

24
cryptography/asymmetric/introduction.md
View File

@@ -1,24 +0,0 @@
---
title: Asymmetric Cryptography in Monero
has_children: true
parent: Cryptography in Monero
---
# Asymmetric Cryptography in Monero
{: .warning}
Author is nowhere close to being a cryptographer. Be sceptical on accuracy.
Before we get to Monero specific stuff, a little bit of context. We are talking asymmetric cryptography here.
The "asymmetric" simply means the are two keys:
* the private key (used primarily for signing data and for decrypting data)
* the public key (used primarily for signature verification and encrypting data)
This is in contrast to symmetric cryptography which uses a single key. This key is a secret shared among the parties.
Historically, asymmetric cryptography was based on the problem of factorization of a very large integers
back into prime numbers (which is practically impossible for large enough integers).
Recently, asymmetric cryptography is based on a mathematical notion of elliptic curves.
Edwards25519 is a specific, well researched and standardized elliptic curve used in Monero.

53
cryptography/asymmetric/key-image.md
View File

@@ -1,53 +0,0 @@
---
title: Monero Private Key Image
parent: Asymmetric Cryptography in Monero
grand_parent: Cryptography in Monero
---
# Monero Private Key Image
{: .warning}
Author is nowhere close to being a cryptographer. Be sceptical on accuracy.
Private key image serves to detect double spending attempts.
In Monero funds are always sent to a one-time public key `P`.
Related one-time private key `x` is specific to unspent output.
As output can be spent only once (in whole), the related private key can be used only once as well.
Thus, specific private key image `I` being present on the blockchain means
that related output was already spent, and subsequent attempts must not be allowed.
This whole scheme is necessary because Monero uses Ring Signatures
which make it impossible to know whom exactly signed the transaction.
This is why a simple Bitcoin-like double spending check wouldn't work here.
## Definition
I = x*Hp(P)
Where:
* `I` - private key image (or "key image" for short)
* `x` - one-time private key used to unlock an unspent output
* `P` - one-time public key of an unspent output
* `Hp()` - hash function accepting an EC point as an argument
The `P` comes from this:
P = xG
Where `G` is the [edwards25519](/cryptography/asymmetric/edwards25519) base point.
Substitute `P` with `xG` and we get:
I = x*Hp(xG)
The key image `I` is a one-way function of the private key `x`.
## Reference
* [StackExchange answer](https://monero.stackexchange.com/questions/2883/what-is-a-key-image)
* [Another SE answer](https://monero.stackexchange.com/questions/2158/what-is-moneros-mechanism-for-defending-against-a-double-spend-attack)
* [Critical bug](https://getmonero.org/2017/05/17/disclosure-of-a-major-bug-in-cryptonote-based-currencies.html) regarding key image verification that was once present in Monero

62
cryptography/asymmetric/private-key.md
View File

@@ -1,62 +0,0 @@
---
title: Private Keys in Monero
parent: Asymmetric Cryptography in Monero
grand_parent: Cryptography in Monero
---
# Private Keys in Monero
{: .warning}
Author is nowhere close to being a cryptographer. Be sceptical on accuracy.
In Monero, the root private key is generated [randomly](/cryptography/prng). Other private keys are derived deterministically from the root private key.
Private key must be kept secret.
Private key is a **large integer** impossible to guess, like:
`108555083659983933209597798445644913612440610624038028786991485007418559037440`
Private key is 256 bits long.
Private key is a **scalar**, meaning it is a single value.
In equations scalars are represented by **lowercase letters**.
## Relation to Ed25519
Being simply a random integer, private key is not specific to any particular asymmetric cryptography scheme.
In context of Monero EC cryptography the private key is a number the base point `G` is multiplied by.
The result of the multiplication is the public key `P` (another point on the curve).
Multiplication of a point by a number has a very special definition in EC cryptography.
See this [this guide](https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/) for details.
### Key strength
Before deriving the public key, private key is subject to modulo `l`,
where `l` is the maximum scalar allowed by the [edwards25519 curve](/cryptography/asymmetric/edwards25519).
The `l` is on the order of 2^252, so the effective key strength is technically 252 bits, not 256 bits.
This is standard for EC cryptography and is more of a cosmetic nuance than any concern.
## Encoding
In user-facing contexts, the private key integer is:
1. Taken modulo `l` to avoid malleability
2. Put as array of 32 bytes in a [little-endian](https://en.wikipedia.org/wiki/Endianness#Little) direction (the first byte is the least significant)
3. Converted to hexadecimal form, like: `b3588a87056fb21dc4d052d59e83b54293882e646b543c29478e4cf45c28a402`
## Private spend key
Private spend key is used to spend moneros.
More specifically, it is used to build one-time private keys which allow to spend related outputs.
## Private view key
Private view key is used to recognize your incoming transactions on the otherwise opaque blockchain.
## One-time private keys
One-time private key like construct is used in [stealth addresses](https://monero.stackexchange.com/questions/1409/constructing-a-stealth-monero-address).

46
cryptography/asymmetric/public-key.md
View File

@@ -1,46 +0,0 @@
---
title: Public Keys in Monero
parent: Asymmetric Cryptography in Monero
grand_parent: Cryptography in Monero
---
# Public Keys in Monero
{: .warning}
Author is nowhere close to being a cryptographer. Be sceptical on accuracy.
Public key is deterministically derived from private key based on [edwards25519 curve](/cryptography/asymmetric/edwards25519) with a little Monero-specific twist.
Public key is meant to be shared. Assuming correct implementation, it is not practically possible to recover private key from public key.
Public key is a **point (x,y)** on the elliptic curve.
In equations points are represented by **uppercase letters**.
In user-facing contexts, public key is encoded in a [little-endian](https://en.wikipedia.org/wiki/Endianness#Little) hexadecimal form, like:
`016a941812293cf9a86071060fb090ab38d67945e659968cb8cf30e1bc725683`
## Deriving public key
Say:
* P is a public key
* x is a private key
* G is a "base point"; this is simply a constant specific to [edwards25519](/cryptography/asymmetric/edwards25519); this point lies on the elliptic curve
Then:
P = xG
The public key is simply the base point (G) multiplied by the private key (x).
Multiplying the point is adding the point to itself a number of times.
However, the addition is **not** a simple vector addition. It has a very specific
definition nicely described in [this article](https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/).
What is important is that result of addition is always a point on the curve.
For example, G + G is another point on the curve.
## Use cases
[Monero address](/public-address/standard-address) is composed of public spend key and public view key.
These keys are used to build stealth addresses to receive payments.

24
cryptography/base58.md
View File

@@ -1,24 +0,0 @@
---
title: Base58
parent: Cryptography in Monero
---
# Base58
Base58 is a binary-to-text encoding scheme. It is similar to Base64 but has been modified to avoid both non-alphanumeric characters and letters which might look ambiguous when printed. The characters excluded in relation to Base64 are: `IOl0+/`
Base58 does not strictly specify the format. This results in some implementations being incompatible with others, for example with regard to alphabet order.
For details, see [Wikipedia](https://en.wikipedia.org/wiki/Base58).
## Base58 in Monero
Monero has its own variant of Base58.
In Monero the Base58 encoding is performed in 8-byte blocks, except the last block which is the remaining (8 or less) bytes .
The 8-byte block converts to 11 or less Base58 characters. If the block converted to less than 11 characters, the output is padded with "1"s (0 in Base58). The final block is padded as well to whatever would be the maximum size of this number of bytes encoded in Base58.
The advantage of Monero implementation is that output is of a fixed size which is not the case with plain Base58. The disadvantage is that default libraries won't work.
For details, see [reference C++ Base58](https://github.com/monero-project/monero/blob/master/src/common/base58.cpp) implementation and [unofficial Python Base58](https://github.com/bigreddmachine/MoneroPy/blob/master/moneropy/base58.py) implementation.

13
cryptography/introduction.md
View File

@@ -1,13 +0,0 @@
---
title: Cryptography in Monero
has_children: true
---
# Cryptography in Monero
Monero uses a wide variety of cryptographic primitives for various use cases.
Comparing to altcoins, Monero cryptography is considered conservative, sound and robust.
Comparing to Bitcoin, Monero uses much more primitives, and some of them are more advanced, especially those related to privacy and Proof of Work.
Some choices are deliberately non-standard (for better or worse) - oftentimes a legacy of the CryptoNote protocol.

42
cryptography/keccak-256.md
View File

@@ -1,42 +0,0 @@
---
title: Keccak-256 Hash Function
parent: Cryptography in Monero
---
# Keccak-256 Hash Function
Monero employs Keccak as a hashing function. In most context specifically Keccak-256 is used,
providing 32-byte hashes.
Keccak is the leading hashing function, designed by non-NSA designers.
Keccak won [NIST competition](https://en.wikipedia.org/wiki/NIST_hash_function_competition) to become the official SHA3.
## Use Cases
Monero does **not** employ Keccak for Proof-of-Work. Instead, Keccak is used for:
* random number generator
* block hashing
* transaction hashing
* stealth address private key image (for double spend protection)
* public address checksum
* RingCT
* multisig
* bulletproofs
...and likely a few other things.
## Keccak-256 vs SHA3-256
SHA3-256 is Keccak-256, except that NIST changed the padding.
For this reason, the original Keccak-256 gives a different hash value than NIST SHA3-256.
Monero uses original Keccak-256.
The NIST standard was only published on August 2015, while Monero went live on 18 April 2014.
## Reference
* [Keccak source code used in Monero](https://github.com/monero-project/monero/blob/5c2dfe157b48a486eb2b92dcf8789b3b1eb20f60/src/crypto/keccak.c)
* [SHA3 on Wikipedia](https://en.wikipedia.org/wiki/SHA-3)
* [Keccak-256 vs SHA3-256](https://ethereum.stackexchange.com/questions/550/which-cryptographic-hash-function-does-ethereum-use) explained on Ethereum stackexchange
* [Online tool to calculate Keccak-256 and SHA3-256](https://emn178.github.io/online-tools/keccak_256.html)

22
index.md
View File

@@ -1,22 +0,0 @@
---
title: Home
layout: home
nav_exclude: true
---
# Unofficial Monero Documentation
GetMonero.dev organizes basic technical knowledge on Monero in one place. It is a continuation of [the MoneroDocs repo](https://github.com/monerodocs/md).
The goal of this website is to supplement the official Monero documentation. This website is maintained by [MAGIC Grants](https://magicgrants.org), a 501(c)(3) public charity.
Common pages include:
* [Using monerod](/interacting/monerod)
* [Using monero-wallet-cli](/interacting/monero-wallet-cli)
* [Using monero-wallet-gui](/interacting/monero-wallet-gui)
* [Using monero-wallet-rpc](/interacting/monero-wallet-rpc)
Please submit your feedback and corrections directly on [GitHub](https://github.com/MAGICGrants/getmonero.dev/issues).
This website is provided for educational purposes only. Any references to third parties are not endorsements.

6
infrastructure/infrastructure.md
View File

@@ -1,6 +0,0 @@
---
title: Infrastructure
has_children: true
---
# Infrastructure

118
infrastructure/monero-pulse.md
View File

@@ -1,118 +0,0 @@
---
title: MoneroPulse
parent: Infrastructure
---
# MoneroPulse
## What is MoneroPulse?
MoneroPulse is infrastructure for emergency checkpointing the blockchain.
It aims to mitigate chain-splits resulting from consensus bugs (like [this one from 2014](https://monero.stackexchange.com/questions/421/what-happened-at-block-202612/424#424)).
Effectively, MoneroPulse operators can publish which fork they consider the valid one. Technically, the "checkpoint" they publish is a block hash and the block height.
By default, Monero full node will simply warn users when MoneroPulse checkpoint does not match the fork it is on. The error will be present in the log and on the console in red. Users are free to discard it. Ideally though, users should consult community on what is going on, and make educated decission on whether to follow the checkpoint-compatible fork or the default fork.
Users can also set auto-enforcing the checkpoints via `--enforce-dns-checkpointing` option to `monerod`. In case of mismatch, `monerod` will rollback the local blockchain by a few blocks. Eventually, the alternative ("fixed") fork will get heavier and the node will follow it, leaving the "invalid" fork behind. This option is recommended for unattended full nodes.
Summing up, MoneroPulse is emergency checkpointing mechanism. It is opt-in for the users.
## MoneroPulse is DNS based
The ckeckpoints are stored as DNS TXT records for domains owned by MoneroPulse operators.
To get the idea you can access the checkpoints manually with any DNS client:
Try:
dig -t txt checkpoints.moneropulse.net +dnssec
Result:
(cut)
;; ANSWER SECTION:
checkpoints.moneropulse.net. 299 IN TXT "1288616:875ac1bc7aa6c5eedc5410abb9c694034f9e7f79dce4c60698baf37009cb6365"
checkpoints.moneropulse.net. 299 IN TXT "375000:c80c23e387585e12ffb6649d678e9ba328181797b9583a6d8911b77e25375737"
checkpoints.moneropulse.net. 299 IN TXT "325000:4260d56368267bc2a70dd58d73c5ecf23b4e4d96e63c29a868e4a679b0741c7f"
checkpoints.moneropulse.net. 299 IN TXT "233000:4f69bec2af6c0852412bdd10c19e6af10c8d738fe2618b5511a98efd03ab477e"
checkpoints.moneropulse.net. 299 IN TXT "450000:4d098b511ca97723e81737c448343cfd4e6dadb3d8a0e757c6e4d595e6e48357"
checkpoints.moneropulse.net. 299 IN TXT "250000:f59d31839bd909ec8830b4f7f66ff213f0bd006334c8523daee452725e5c7a79"
checkpoints.moneropulse.net. 299 IN TXT "550000:c2e80a636438bd9f7a7ab432a6ad297e35540d80ff5b868bca098124cad2ff8c"
checkpoints.moneropulse.net. 299 IN TXT "650000:1d567f2b491324375a825895c5e7b52857b38e4fed0e42c40909c2d52240b4e0"
checkpoints.moneropulse.net. 299 IN TXT "800000:2ced10aa85357ab6c14bb12b6b56d1dde28940820dda30911b73a5cc9a301760"
checkpoints.moneropulse.net. 299 IN TXT "850000:00e2b557dde9fd4a9e2e3dd7ddac962f5ca475eb1095bc50aa757fd1218ab0a5"
checkpoints.moneropulse.net. 299 IN TXT "900000:d9958d0e7dcf91a5a7b11de225927bf7efc6eb26240315ce12372be902cc1337"
checkpoints.moneropulse.net. 299 IN TXT "913193:5292d5d56f6ba4de33a58d9a34d263e2cb3c6fee0aed2286fd4ac7f36d53c85f"
checkpoints.moneropulse.net. 299 IN TXT "913269:f8302e6b8ba1c49aad9a854b8d6c79d8272c6239dcbba5a75ed0784c1d4f56a1"
checkpoints.moneropulse.net. 299 IN TXT "350000:74da79f6a136969abd6364bd3d37af273c408d6471e8ab598e80569b42415f86"
checkpoints.moneropulse.net. 299 IN TXT "400000:1b2b0e7a30e59691491529a3d506d1ba3d6052d0f6b52198b7330b28a6f1b6ac"
checkpoints.moneropulse.net. 299 IN TXT "500000:2428f0dbe49796be05ed81b347f53e1f7f44aed0abf641446ec2b94cae066b02"
checkpoints.moneropulse.net. 299 IN TXT "600000:f5828ebf7d7d1cb61762c4dfe3ccf4ecab2e1aad23e8113668d981713b7a54c5"
checkpoints.moneropulse.net. 299 IN TXT "700000:12be9b3d210b93f574d2526abb9c1ab2a881b479131fd0d4f7dac93875f503cd"
checkpoints.moneropulse.net. 299 IN TXT "300000:0c1cd46df6ccff90ec4ab493281f2583c344cd62216c427628990fe9db1bb8b6"
checkpoints.moneropulse.net. 299 IN RRSIG TXT 13 3 300 20180922151845 20180920131845 35273 moneropulse.net. 8CyqtsM2f9o6OHZYqtGPVf+8gcFM+eUyoMi29LlkcLtK1AXbZlKqCcdN NvdvB+4OzepmpTanSc+TbLWbz/sIzA==
Please note the DNSSEC signature entry at the end.
The checkpoints are mirrored on several DNS servers:
Mainnet:
checkpoints.moneropulse.se
checkpoints.moneropulse.org
checkpoints.moneropulse.net
checkpoints.moneropulse.co
Stagenet:
stagenetpoints.moneropulse.se
stagenetpoints.moneropulse.org
stagenetpoints.moneropulse.net
stagenetpoints.moneropulse.co
Testnet:
testpoints.moneropulse.se
testpoints.moneropulse.org
testpoints.moneropulse.net
testpoints.moneropulse.co
## MoneroPulse as attack vector
It is worth noting that MoneroPulse does not produce blocks and cannot split the chain on its own. It only suggests the valid fork.
Should MoneroPulse got entirely compromised, attacker could stop all auto-enforcing nodes from advancing, by feeding them with the fake checkpoint. This is partially mitigated by DNSSEC and by operating multiple domains. Monero expects checkpoints are consistent across domains. Thus, compromising a single domain or registrar should not lead to any disruption.
MoneroPulse also increases the say of its operators in case of possible contentious hard forks. While well intended, this effectively centralizes more power in hands of core developers, or whomever is at the time running MoneroPulse infrastructure.
### Who are MoneroPulse operators?
MoneroPulse is operated by selected core developers.
## Fixing "WARNING: no two valid MoneroPulse DNS checkpoint records were received"
This means DNS server you are using does not ackonwledge the +dnssec flag necessary for securely query for checkpoints.
By default, your operating system will use DNS server provided by your Internet Service Provider.
To fix this warning, change your DNS server either system-wide in your network configuration, or specifically for `monerod`.
Many people find Google's or Cloudflare's DNS servers superior to those offered by their ISPs.
Using Google DNS:
DNS_PUBLIC=tcp://8.8.8.8 ./monerod
Using Cloudflare DNS:
DNS_PUBLIC=tcp://1.1.1.1 ./monerod
## Reference
* [StackExchange answer](https://monero.stackexchange.com/questions/679/what-is-moneropulse?noredirect=1&lq=1)
* [Reddit answer](https://www.reddit.com/r/Monero/comments/419qdd/p2p4warning_no_two_valid_moneropulse_dns/)
* [Monero source code](https://github.com/monero-project/monero/blob/ff7dc087ae5f7de162131cea9dbcf8eac7c126a1/src/checkpoints/checkpoints.cpp)

77
infrastructure/networks.md
View File

@@ -1,77 +0,0 @@
---
title: Mainnet, Stagenet, Testnet
parent: Infrastructure
---
# Networks
Monero offers three separate networks and blockchains: **mainnet**, **stagenet** and **testnet**. Every blockchain has its own genesis block and is entirely seperate from others. Also, corresponding p2p networks are separate.
## Mainnet
Mainnet is the "production" network and blockchain.
Mainnet is the only blockchain where XMR units have value.
Mainnet is what people mean by default.
Default TCP ports (listening):
* 18080 - p2p network
* 18081 - JSON-RPC server
* 18082 - ZMQ server
## Stagenet
Stagenet is what you need to learn Monero safely.
Stagenet is technically equivalent to mainnet, both in terms of features and consensus rules. Similar to mainnet, use the [latest official Monero release](https://getmonero.org/downloads/) to be compatible with stagenet.
To get started:
* Connect your GUI or CLI to stagenet open node **monero-stagenet.exan.tech:38081**
* Get free stagenet XMR from [stagenet faucet](https://melo.tools/faucet/stagenet/) or [stagenet faucet 2](https://stagenet-faucet.xmr-tw.org/)
* Check the [stagenet block explorer 1](https://stagenet.xmrchain.net/) or [stagenet block explorer 2](https://melo.tools/explorer/stagenet/)
Default TCP ports (listening):
* 38080 - p2p network
* 38081 - JSON-RPC server
* 38082 - ZMQ server
Stagenet was introduced in March 2018 as part of Monero 0.12.0.0.
## Testnet
As a normal user, use [stagenet](#stagenet) instead. Testnet is for developers.
Testnet is the "experimental" network and blockchain where things get released long before mainnet.
Testnet forks early and often. Most of the time you need to compile Monero from source to be compatible with testnet. Otherwise you will get stuck on the old not-forked version.
To get started:
* Build Monero from [source](https://github.com/monero-project/monero)
* Connect your GUI or CLI to testnet open node **monero-testnet.exan.tech:28081**
* Get free XMR from [testnet faucet](https://melo.tools/faucet/testnet/)
* Check the [testnet block explorer 1](https://testnet.xmrchain.net/) or [testnet block explorer 2](https://melo.tools/explorer/testnet/)
Default TCP ports (listening):
* 28080 - p2p network
* 28081 - JSON-RPC server
* 28082 - ZMQ server
## Private Testnet
You can also create your private version of the testnet.
Private testnet gives more flexibility to arange for specific situations for developers.
Check the [private testnet guide](https://github.com/moneroexamples/private-testnet).
## Why stagenet and testnet coins have no value?
If mainnet and stagenet are technically equivalent then why only mainnet coins have value?
This is simply the convention community embraced. Value only comes from a shared believe that mainnet coins will be accepted by other people in the future.

80
infrastructure/tor-onion-p2p-seed-nodes.md
View File

@@ -1,80 +0,0 @@
---
title: Tor Onion Seed Nodes for Monero P2P Network
parent: Infrastructure
---
# Tor onion seed nodes for Monero network
## When this is necessary?
This is only necessary if you run a full node and you want to propagate locally-originating transactions over Tor (using `tx-proxy` option, see [monerod reference](/interacting/monerod/#tori2p)). This allows you to mask your IP (as transaction originator) against P2P network surveillence, on top of Monero's built-in Dandelion++.
## What are P2P seed nodes?
Your monero daemon will discover other P2P nodes but it needs to start somewhere. These starting nodes are known as "seed nodes". For clearnet the seed nodes are hardcoded in the software so no configuration is needed.
For the Tor network there are no hardcoded seed nodes. You must specify them manually by using the `add-peer` option in `monero.conf`.
## Config snippet
These were tested working as of 2020-01-11. They are ran by volunteers and are **not guaranteed** to work or be maintained. See below how you can quickly test them.
```
# monero.conf snippet
# ...
add-peer=moneroxmrxw44lku6qniyarpwgznpcwml4drq7vb24ppatlcg4kmxpqd.onion:18080
add-peer=monerozf6koypqrt.onion:18080
add-peer=zbjkbsxc5munw3qusl7j2hpcmikhqocdf4pqhnhtpzw5nt5jrmofptid.onion:18083 # https://github.com/monero-project/monero/blob/master/src/p2p/net_node.inl
add-peer=rno75kjcw3ein6i446sqby2xkyqjarb75oq36ah6c2mribyklzhurpyd.onion:28083 # it is mainnet despite the weird port
add-peer=sqzrokz36lgkng2i2nlzgzns2ugcxqosflygsxbkybb4xn6gq3ouugqd.onion:18083 # very flaky, works 1 in 3 times
add-peer=blzchctiibfjfvtukctsydhquucz2oajnxnfc5hh4ix35gyqjhdnaqqd.onion:18083 # full node by author of monerodocs.org
# ...
```
## How to test onion seed nodes?
You need Tor daemon installed and running on your laptop. You will also need `torsocks` command line tool that either comes with Tor or needs to be installed separately.
### Test using torsocks and telnet
You need tor, torsocks and telnet installed.
To test speficic onion:
torsocks telnet moneroxmrxw44lku6qniyarpwgznpcwml4drq7vb24ppatlcg4kmxpqd.onion 18080
The expected output (domain resolution errors are fine):
```
1610372702 ERROR torsocks[11332]: Unable to resolve. Status reply: 4 (in socks5_recv_resolve_reply() at socks5.c:677)
Trying 127.42.42.0...
Connected to moneroxmrxw44lku6qniyarpwgznpcwml4drq7vb24ppatlcg4kmxpqd.onion.
Escape character is '^]'.
```
### Test using torsocks and proxychains
You need tor, torsocks and proxychains installed.
To test specific onion:
proxychains nmap -Pn -p 18080 moneroxmrxw44lku6qniyarpwgznpcwml4drq7vb24ppatlcg4kmxpqd.onion
The expected output (example):
````
[proxychains] Strict chain ... 127.0.0.1:9050 ... moneroxmrxw44lku6qniyarpwgznpcwml4drq7vb24ppatlcg4kmxpqd.onion:18080 ... OK
Nmap scan report for moneroxmrxw44lku6qniyarpwgznpcwml4drq7vb24ppatlcg4kmxpqd.onion (224.0.0.1)
Host is up (0.74s latency).
rDNS record for 224.0.0.1: all-systems.mcast.net
PORT STATE SERVICE
18080/tcp open unknown
````
## Not enough onion seed nodes
The onion seed nodes are a scarce resource. Most nodes are only maintained temporarily by their authors.
You can greatly contribute to Monero P2P network performance and resillience by running onion-enabled monero full node.

38
interacting/download-monero-binaries.md
View File

@@ -1,38 +0,0 @@
---
title: Download Monero
parent: Interacting with Monero
---
# Download Monero
A single archive contains all you need to start using Monero (the full node and the wallet).
We recommend downloading Monero binaries directly from GitHub:
* GUI + CLI: [https://github.com/monero-project/monero-gui/releases](https://github.com/monero-project/monero-gui/releases)
* CLI only: [https://github.com/monero-project/monero/releases](https://github.com/monero-project/monero/releases)
GUI is a graphical desktop wallet.
CLI is a commandline desktop wallet.
If you need more guidance check [download Monero](https://getmonero.org/downloads) section on Monero website.
It is critical to [verify the signature](/interacting/verify-monero-binaries) of downloaded archive.
## Which version to download?
Download the latest version matching your operating system and processor architecture.
The CLI version is released earlier and is suitable for server deployments.
The GUI version contains both CLI and GUI. It is preferable for end-users.
All versions contain a full node and a wallet.
## Why prefer GitHub over getmonero.org?
Binaries appear earlier on GitHub.
On top of that, if you fail to properly verify the signature, GitHub is safer, simply because you don't need to trust a separate website to not be compromised.
Obviously, you should still carefully verify the signature for each release. Signature verification is always the primary line of defense.

92
interacting/monero-blockchain-import.md
View File

@@ -1,92 +0,0 @@
---
title: monero-blockchain-import
parent: Interacting with Monero
---
# `monero-blockchain-import` - Reference
{: .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
The tool imports bootstrap file `blockchain.raw` to your full node.
This could be useful if you want to decouple download from verification for any reason (like testing performance in isolation).
In this case, you may download the `blockchain.raw` file from [https://downloads.getmonero.org/blockchain.raw](https://downloads.getmonero.org/blockchain.raw).
Ideally though, you should use your own trusted `blockchain.raw` file that you [exported](/interacting/monero-blockchain-export) earlier.
Please note that importing `blockchain.raw` will **not** speed up the process over syncing up from p2p network.
This is because usual bottlenecks are disk IO and verification, not the download.
The tool works on your local files. It does not require `monerod` running.
## Syntax
`./monero-blockchain-import [options]`
Example:
`./monero-blockchain-import --help`
## Running
Go to directory where you unpacked Monero.
`./monero-blockchain-import --stagenet --output-file=/tmp/blockchain.raw`
## Options
### Help
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--help` | Enlist available options.
### Pick network
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| (missing) | By default `monero-blockchain-import` assumes the [mainnet](/infrastructure/networks#mainnet) blockchain.
| `--stagenet` | Import [stagenet](/infrastructure/networks#stagenet) blockchain.
| `--testnet` | Import [testnet](/infrastructure/networks#testnet) blockchain.
### Logging
Specifying the log file path is not supported.
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--log-level` | `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. Example: <br />`./monero-blockchain-import --log-level=1`
### Input
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--input-file` | Full path to raw blockchain file. The default is `$DATA_DIR/export/blockchain.raw`.
| `--block-stop` | Only import up to this block height. By default import all blocks (value `0`).
| `--pop-blocks` | Discard specified number of blocks from the tip of the bootstrapped blockchain. By default don't discard anything (value `0`).
### Output
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--data-dir` | Full path to data directory. This is where the blockchain, log files, and p2p network memory are stored. For defaults and details see [data directory](/interacting/overview/#data-directory).
| `--count-blocks` | Count blocks in the bootstrap file and exit.
| `--drop-hard-fork` | Whether to drop hard fork data. Off by default (`0`).
| `--database` | The only valid value seems to be `lmdb` (the default).
### Performance
| Option | Description
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--dangerous-unverified-import` | The safe default is to run verification (value `0`). You can enable `--dangerous-unverified-import` if you are importing from your own and trusted blockchain.raw (which we assume was already verified). The "dangerous" mode will greatly speed up the process.
| `--batch` | Whether to save to disk on an ongoing basis (the default, value `1`) or maybe do everything in RAM and save everything in the end (value `0`). No batching is only effective in combination with no verification (`--dangerous-unverified-import`). See also `--batch-size`.
| `--batch-size` | How often to save to disk expressed in number of blocks. By default save every `5000` blocks (when verifying) or every `20000` blocks (when not verifying). Big batches are faster but require more RAM.
| `--resume` | Resume from current height if output database already exists (the default, value `1`). Changing to `--resume=0` doesn't change much &mdash; existing blocks are skipped pretty quickly and the process is resumed anyway.
## Reference
* [https://github.com/monero-project/monero/tree/master/src/blockchain_utilities](https://github.com/monero-project/monero/tree/master/src/blockchain_utilities)

361
interacting/monero-wallet-cli.md
View File

@@ -1,361 +0,0 @@
---
title: monero-wallet-cli
parent: Interacting with Monero
---
# `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) 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):
| 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
### 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
### Balance
`account` - total balance; list accounts with respective balances
`balance detail` - within the current account, list addresses with respective balances
`refresh` - force refresh the balance and transactions by pulling latest blocks from the full node; this is often useful because auto-refresh only kicks in once in 90 seconds
### Manage accounts
`account`
`account new`
`account switch`
`account label`
### Manage addresses
`address all`
`address new`
`address label`
### View transactions
`show_transfers` - show all transactions on the current account; optionally provide a filter: `in` | `out` | `pending` | `failed` | `pool` | `coinbase`; optionally provide subaddress index for output selection
`show_transfer <txid>` - show details of specific transaction
`incoming_transfers [available|unavailable] [verbose] [index=<N1>[,<N2>[,...]]]` - show the incoming transactions, all or filtered by availability and address index within current account; this will only show confirmed transactions; you will not see transactions awaiting in the mempool
`get_tx_note <txid>` - get a string note for transaction id
`export_transfers [in|out|all|pending|failed|pool|coinbase] [index=<N1>[,<N2>,...]] [<min_height> [<max_height>]] [output=<filepath>] [option=<with_keys>]` - exports a list of all transfer information to a CSV file. You can filter by type `[in|out|all|pending|failed|pool|coinbase]`, by index, by minimum and maximum block height, specify the output path for the CSV file, and optionally include the tx private keys (if available) with the export.
### Keys and Passwords
#### 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
#### Wallet password
`password` - change wallet password; this password is used to encrypt the local wallet files; it does not change secret keys or backups
### 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`
`sign_multisig <filename>`
### Hardware wallet
`hw_reconnect` - attempts to reconnect HW wallet
### Mining
`start_mining`
`stop_mining`
### Advanced
#### Outputs
`unspent_outputs` - show a list of, and a histogram of unspent outputs (indivisible pieces of your total balance)
`export_outputs <file>` -> `import_outputs <file>` - helps with cold spending; export outputs from a view-wallet to the cold-wallet to make it aware of what had been sent to it
`mark_output_spent <amount>/<offset> | <filename> [add]` - "blackball"/mark an output known to be spent, so that it will no longer be selected as a decoy
`mark_output_unspent <amount>/<offset>` - unmark an output not known to be spent, so that it will possibly be selected as a decoy
`is_output_spent <amount>/<offset>`
#### Key images
`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
#### 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>`
### Debugging
`rescan_spent` - rescan the blockchain for spent outputs; sometimes, the wallet's idea of what outputs are spent and what outputs are not get out of sync with the blockchain. This can happen if you exit the wallet without saving after sending a tx, or if it crashes. This will look for the key images on the blockchain to make sure it's up to date.
### Cosmetics
`donate <amount>` - donate `<amount>` to development team
`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)
### Legacy
`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
`locked_sweep_all` - see
`rescan_bc` - rescan the blockchain from scratch, losing any information which can not be recovered from the blockchain itself
TODO: document remaining commands

77
interacting/monero-wallet-gui.md
View File

@@ -1,77 +0,0 @@
---
title: monero-wallet-gui
parent: Interacting with Monero
---
# `monero-wallet-gui` - Reference
## Overview
### Desktop GUI wallet
The "official" desktop 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.
### Depends on the full node
Wallet connects to a [full node](/interacting/monerod) 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.
### User guide PDF
A nice PDF guide is available in the catalog you unpacked Monero. Make sure to check it out!
The online living version is also available:<br />
[https://github.com/monero-ecosystem/monero-GUI-guide/blob/master/monero-GUI-guide.md](https://github.com/monero-ecosystem/monero-GUI-guide/blob/master/monero-GUI-guide.md)
## Syntax
`./monero-wallet-gui [options]`
Example:
`./monero-wallet-gui --log-file=/dev/null`
## 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`
In a separate terminal window, run the wallet:
`./monero-wallet-gui`
## 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.

2857
interacting/monero-wallet-rpc.md
View File

File diff suppressed because it is too large Load Diff

365
interacting/monerod.md
View File

@@ -1,365 +0,0 @@
---
title: monerod
parent: Interacting with Monero
---
# `monerod` - Reference
## Overview
### Connects you to Monero network
The Monero daemon `monerod` keeps your computer synced up with the Monero network.
It downloads and validates the blockchain from the p2p network.
### Not aware of your private keys
`monerod` is entirely decoupled from your wallet.
`monerod` does not access your private keys - it is not aware of your transactions and balance.
This allows you to run `monerod` on a separate computer or in the cloud.
In fact, you can connect to a remote `monerod` instance provided by a semi-trusted 3rd party. Such 3rd party will not be able to steal your funds. This is very handy for learning and experimentation.
However, there are privacy and reliability implications to using a remote, untrusted node. For any real business **you should be running your own full node**.
## Syntax
`./monerod [options] [command]`
Options define how the daemon should be working. Their names follow the `--option-name` pattern.
Commands give access to specific services provided by the daemon. Commands are executed against the running daemon.
Their names follow the `command_name` pattern.
## Running
Go to directory where you unpacked Monero.
The [stagenet](/infrastructure/networks) is what you should be using for learning and experimentation.
```
./monerod --stagenet --detach # run as a daemon in background
tail -f ~/.bitmonero/stagenet/bitmonero.log # watch the logs
./monerod --stagenet exit # ask daemon to exit gracefully
```
The [mainnet](/infrastructure/networks) is when you want to deal with the real XMR.
```
./monerod --detach # run as a daemon in background
tail -f ~/.bitmonero/bitmonero.log # watch the logs
./monerod exit # ask daemon to exit gracefully
```
## Options
Options define how the daemon should be working. Their names follow the `--option-name` pattern.
The following groups are only to make reference easier to follow. The daemon itself does not group options in any way.
#### Help and version
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--help` | Enlist available options.
| `--version` | Show `monerod` version to stdout. Example output: <br />`Monero 'Oxygen Orion' (v0.17.1.8-release)`
| `--os-version` | Show build timestamp and target operating system. Example output:<br />`OS: Linux #65-Ubuntu SMP Thu Dec 10 12:01:51 UTC 2020 5.4.0-59-generic`.
| `--check-updates` | One of: `disabled` \| `notify` \| `download` (=`notify` by default). Check for new versions of Monero and optionally download it. You should probably prefer your OS package manager to do the update, if possible. There is also unimplemented `update` option shown by the help system.
#### Pick Monero network (blockchain)
| 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.
#### Logging
| Option | Description
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------
| `--log-file` | Full path to the log file. Example (mind file permissions): <br/>`./monerod --log-file=/var/log/monero/mainnet/monerod.log`
| `--log-level` | `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. Temporarily changing to `1` allows for much better understanding of how the full node operates. Example: <br />`./monerod --log-level=1`
| `--max-log-file-size` | Soft limit in bytes for the log file (=104850000 by default, which is just under 100MB). Once log file grows past that limit, `monerod` 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 monerod from managing the log files.
| `--max-log-files` | 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.
#### Server
`monerod` defaults are adjusted for running it occasionally on the same computer as your Monero wallet.
The following options will be helpful if you intend to have an always running node &mdash; most likely on a remote server or your own separate PC.
| Option | Description
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--config-file` | Full path to the [configuration file](/interacting/monero-config-file). By default `monerod` looks for `bitmonero.conf` in Monero [data directory](/interacting/overview/#data-directory).
| `--data-dir` | Full path to data directory. This is where the blockchain, log files, and p2p network memory are stored. For defaults and details see [data directory](/interacting/overview/#data-directory).
| `--pidfile` | Full path to the PID file. Works only with `--detach`. Example: <br />`./monerod --detach --pidfile=/run/monero/monerod.pid`
| `--detach` | Go to background (decouple from the terminal). This is useful for long-running / server scenarios. Typically, you will also want to manage `monerod` daemon with systemd or similar. By default `monerod` runs in a foreground.
| `--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-zmq` | Disable ZMQ RPC server. You **should** use this option to limit attack surface and number of unnecessarily open ports (the ZMQ server is unfinished thing and you are unlikely to ever use it).
| `--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) 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
The following options define how your node participates in Monero peer-to-peer network.
This is for node-to-node communication. The following options do **not** affect [wallet-to-node](#node-rpc-api) interface.
The node and peer words are used interchangeably.
| Option | Description
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--p2p-bind-ip` | IPv4 network interface to bind to for p2p network protocol. Default value `0.0.0.0` binds to all network interfaces. This is typically what you want. <br /><br />You must change this if you want to constrain binding, for example to force working through Tor via torsocks: <br />`DNS_PUBLIC=tcp://1.1.1.1 TORSOCKS_ALLOW_INBOUND=1 torsocks ./monerod --p2p-bind-ip 127.0.0.1  --no-igd  --hide-my-port`
| `--p2p-bind-port` | TCP port to listen for p2p network connections. Defaults to `18080` for mainnet, `28080` for testnet, and `38080` for stagenet. You normally wouldn't change that. This is helpful to run several nodes on your machine to simulate private Monero p2p network (likely using private Testnet). Example: <br/>`./monerod --p2p-bind-port=48080`
| `--p2p-external-port` | TCP port to listen for p2p network connections on your router. Relevant if you are behind a NAT and still want to accept incoming connections. You must then set this to relevant port on your router. This is to let `monerod` know what to advertise on the network. Default is `0`.
| `--p2p-use-ipv6` | Enable IPv6 for p2p (disabled by default).
| `--p2p-bind-ipv6-address` | IPv6 network interface to bind to for p2p network protocol. Default value `::` binds to all network interfaces.
| `--p2p-bind-port-ipv6` | TCP port to listen for p2p network connections. By default same as IPv4 port for given nettype.
| `--p2p-ignore-ipv4` | Ignore unsuccessful IPv4 bind for p2p. Useful if you only want to use IPv6.
| `--igd` | Set UPnP port mapping on the router ("Internet Gateway Device"). One of: `disabled` \| `enabled` \| `delayed` (=`delayed` by default). Relevant if you are behind NAT and want to accept incoming P2P network connections. The `delayed` value means it will wait for incoming connections in hope UPnP may not be necessary. After a while w/o incoming connections found it will attempt to map ports with UPnP. If you know you need UPnP change it to `enabled` to fast track the process.
| `--hide-my-port` | `monerod` will still open and listen on the p2p port. However, it will not announce itself as a peer list candidate. Technically, it will return port `0` in a response to p2p handshake (`node_data.my_port = 0` in `get_local_node_data` function). In effect nodes you connect to won't spread your IP to other nodes. To sum up, it is not really hiding, it is more like "do not advertise".
| `--seed-node` | Connect to a node to retrieve other nodes' addresses, and disconnect. If not specified, `monerod` will use hardcoded seed nodes on the first run, and peers cached on disk on subsequent runs.
| `--add-peer` | Manually add node to local peer list, `host:port`. Syntax supports IP addresses, domain names, onion and i2p hosts.
| `--add-priority-node` | Specify list of nodes to connect to and then attempt to keep the connection open. <br /><br />To add multiple nodes use the option several times. Example: <br />`./monerod --add-priority-node=178.128.192.138:18081 --add-priority-node=144.76.202.167:18081`
| `--add-exclusive-node` | Specify list of nodes to connect to only. If this option is given the options `--add-priority-node` and `--seed-node` are ignored. <br /><br />To add multiple nodes use the option several times. Example: <br />`./monerod --add-exclusive-node=178.128.192.138:18081 --add-exclusive-node=144.76.202.167:18081`
| `--out-peers` | Set max number of outgoing connections to other nodes. By default 12. Value `-1` represents the code default.
| `--in-peers` | Set max number of incoming connections (nodes actively connecting to you). By default unlimited. Value `-1` represents the code default.
| `--limit-rate-up` | Set outgoing data transfer limit [kB/s]. By default 2048 kB/s. Value `-1` represents the code default.
| `--limit-rate-down` | Set incoming data transfer limit [kB/s]. By default 8192 kB/s. Value `-1` represents the code default.
| `--limit-rate` | Set the same limit value for incoming and outgoing data transfer. By default (`-1`) the individual up/down default limits will be used. It is better to use `--limit-rate-up` and `--limit-rate-down` instead to avoid confusion.
| `--offline` | Do not listen for peers, nor connect to any. Useful for working with a local, archival blockchain.
| `--allow-local-ip` | Allow adding local IP to peer list. Useful mostly for debug purposes when you may want to have multiple nodes on a single machine.
| `--max-connections-per-ip` | Maximum number of connections allowed from the same IP address.
#### Tor/I2P and proxies
This is experimental. It may be best to start with this [guide](https://github.com/monero-project/monero/blob/master/ANONYMITY_NETWORKS.md#p2p-commands).
| Option | Description
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--tx-proxy` | Send out your local transactions through SOCKS5 proxy (Tor or I2P). Format:<br />`<network-type>,<socks-ip:port>[,max_connections][,disable_noise]` <br /><br />Example:<br />`./monerod --tx-proxy "tx-proxy=tor,127.0.0.1:9050,16"`<br /><br />This was introduced to make publishing transactions over Tor easier (no need for torsocks) while allowing clearnet for blocks at the same time (while torsocks affected everything).<br /><br />Adding `,disable_noise` disables white noise and Dandelion++ (will speed up tx broadcast but is otherwise not recommended). <br /><br />Note that forwarded transactions (those not originating from the connected wallet(s)) will still be relayed over clearnet.
| `--anonymous-inbound` | Allow anonymous incoming connections to your onionized P2P interface. Format: <br />`<hidden-service-address>,<[bind-ip:]port>[,max_connections]`<br /><br />Example:<br />`./monerod --anonymous-inbound "rveahdfho7wo4b2m.onion:18083,127.0.0.1:18083,100"`.<br /><br />Obviously, you first need to setup the hidden service in your Tor config. See the [guide](https://github.com/monero-project/monero/blob/master/ANONYMITY_NETWORKS.md#p2p-commands).
| `--pad-transactions` | Pad relayed transactions to next 1024 bytes to help defend against traffic volume analysis. This only makes sense if you are behind Tor or I2P. See [commit](https://github.com/monero-project/monero/pull/4787).
| `--proxy` | Network communication through proxy. Works with any service that supports SOCKS4, including Tor, i2p, and commercial VPN/proxy services. SOCKS5 support is anticipated in the future. Enabling this setting sends all traffic through this proxy. Can be used in conjunction with `--tx-proxy`, in which case transaction broadcasts originating from the connected wallet(s) will be sent through Tor or i2p as specified in `--tx-proxy`, and all other traffic will be sent through the SOCKS proxy. Format:<br />`<socks-ip:port>`
#### Node RPC API
`monerod` node offers powerful API. It serves 3 purposes:
* provides network data (stats, blocks, transactions, ...)
* provides local node information (peer list, hash rate if mining, ...)
* provides interface for wallets (send transactions, ...)
This API is typically referred to as "RPC" because it is mostly based on JSON/RPC standard.
The following options define how the API behaves.
| Option | Description
|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--public-node` | Advertise to other users they can use this node as a remote one for connecting their wallets. Requires `--restricted-rpc`, `--rpc-bind-ip` and `--confirm-external-bind`. Without `--public-node` the node can still be public (assuming other relevant options are set) but won't be advertised as such on the P2P network. This option will allow wallets to auto-discover public nodes (instead of requiring user to manually find one).
| `--rpc-bind-ip` | IP to listen on. By default `127.0.0.1` because API gives full administrative capabilities over the node. Set it to `0.0.0.0` to listen on all interfaces - but only in connection with one of `*-restricted-*` options **and** `--confirm-external-bind`.
| `--rpc-bind-port` | TCP port to listen on. By default `18081` (mainnet), `28081` (testnet), `38081` (stagenet).
| `--rpc-bind-ipv6-address` | IPv6 to listen on. By default `::1` (localhost). All remarks for `--rpc-bind-ip` are applicable here as well.
| `--rpc-use-ipv6` | Enable IPv6 for RPC server (disabled by default).
| `--rpc-ignore-ipv4` | Ignore unsuccessful IPv4 bind for RPC. Useful if you only want to use IPv6.
| `--rpc-restricted-bind-ip` | IP to listen on with the limited version of API. The limited API can be made public to create an Open Node. By default `127.0.0.1`, set it to `0.0.0.0` to listen on all interfaces.
| `--rpc-restricted-bind-ipv6-address` | IPv6 to listen on with the limited version of API. The limited API can be made public to create an Open Node. By default `::1` (localhost). Set it to `::` to listen on all interfaces.
| `--rpc-restricted-bind-port` | TCP port to listen on with the limited version of API. To be used in combination with `--rpc-restricted-bind-ip`.
| `--confirm-external-bind` | Confirm you consciously set `--rpc-bind-ip` to non-localhost IP and you understand the consequences.
| `--restricted-rpc` | Restrict API to view only commands and do not return privacy sensitive data. Note this does not make sense with `--rpc-restricted-bind-port` because you would end up with two restricted APIs.
| `--rpc-ssl` | Enable TLS on RPC connections. One of: `enabled` \| `disabled` \| `autodetect` (`=autodetect` by default). You **should** enable this if you connect a remote wallet.
| `--rpc-ssl-private-key` | Path to server's private key in PEM format. Generate it with `monero-gen-ssl-cert` tool. This is to facilitate server authentication to client.
| `--rpc-ssl-certificate` | Path to server's certificate in PEM format. Generate it with `monero-gen-ssl-cert` tool. This is to facilitate server authentication to client.
| `--rpc-ssl-allowed-fingerprints` | List of certificate fingerprints to accept. This is a way to authenticate clients.
| `--rpc-ssl-allow-any-cert` | Allow any certificate of connecting client.
| `--rpc-ssl-ca-certificates` | Path to file containing concatenated PEM format certificate(s) to replace system CA(s).
| `--rpc-ssl-allow-chained` | Allow user chained certificates. This is only applicable if user has a "real" CA issued certificate.
| `--rpc-login` | Specify `username[:password]` required to connect to API.
| `--rpc-access-control-origins` | Specify a comma separated list of origins to allow cross origin resource sharing. This is useful if you want to use `monerod` API directly from a web browser via JavaScript (say in a pure-fronted web appp scenario). With this option `monerod` will put proper HTTP CORS headers to its responses. You will also need to set `--rpc-login` if you use this option. Normally though, the API is used by backend app and this option isn't necessary.
| `--disable-rpc-ban` | Do not ban hosts on RPC errors. May help to prevent monerod from banning traffic originating from the Tor daemon.
| `rpc-payment-address` | Restrict RPC to clients sending micropayment to this address.
| `rpc-payment-difficulty` | Restrict RPC to clients sending micropayment at this difficulty in thousands.
| `rpc-payment-credits` | Restrict RPC to clients sending micropayment, yields that many credits per payment in hundreds.
| `rpc-payment-allow-free-loopback` | Allow free access from the loopback address (ie, the local host).
#### Accepting Monero
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
These are advanced options that allow you to optimize performance of your `monerod` node, sometimes at the expense of reliability.
| Option | Description
|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--prune-blockchain` | Pruning saves 2/3 of disk space w/o degrading functionality. For maximum effect this should be used already **on the first sync**. If you add this option later the past data will only be pruned logically w/o shrinking the file size and the gain will be delayed. <br /><br />If you already have unpruned blockchain, see the `monero-blockchain-prune` tool. <br /><br />The drawback is that you will contribute less to Monero P2P network in terms of helping new nodes to sync up (up to 1/8 of normal contribution). You will still be useful regarding relaying new transactions and blocks though.
| `--sync-pruned-blocks` | Accept pruned blocks instead of pruning yourself. It should save network transfer when used with `--prune-blockchain`. See the [commit](https://github.com/monero-project/monero/commit/8330e772f1ed680a54833d25c4d17d09a99ab8d6) and [comments](https://web.getmonero.org/2019/09/08/logs-for-the-dev-meeting-held-on-2019-09-08.html).
| `--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 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 RandomX 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`
| `--bootstrap-daemon-address` | The host:port of a "bootstrap" remote open node that the connected wallets can use while this node is still not fully synced. Example:<br/>`./monerod --bootstrap-daemon-address=opennode.xmr-tw.org:18089`. The node will forward selected RPC calls to the bootstrap node. The wallet will handle this automatically and transparently. Obviously, such bootstraping phase has privacy implications similar to directly using a remote node.
| `--bootstrap-daemon-login` | Specify username:password for the bootstrap daemon login (if required). This considers the RPC interface used by the wallet. Normally, open nodes do not require any credentials.
| `--no-sync` | Do not sync up. Continue using bootstrap daemon instead (if set). See [commit](https://github.com/monero-project/monero/pull/5195).
#### Mining
The following options configure **solo mining** using **CPU** with the standard software stack `monerod`. This is mostly useful for:
* generating your [stagenet](/infrastructure/networks#stagenet) or [testnet](/infrastructure/networks#testnet) coins
* experimentation and learning
* if you have access to vast CPU resources
Be advised though that real mining happens **in pools** like p2pool, and with dedicated miner software like xmrig.
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--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.
| `--bg-mining-ignore-battery` | If true, assumes plugged in when unable to query system power status.
| `--bg-mining-min-idle-interval` | Specify min lookback interval in seconds for determining idle state.
| `--bg-mining-idle-threshold` | Specify minimum avg idle percentage over lookback interval.
| `--bg-mining-miner-target` | Specify maximum percentage cpu use by miner(s).
#### Testing Monero itself
These options are useful for Monero project developers and testers. Normal users shouldn't be concerned with these.
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--keep-alt-blocks` | Keep alternative blocks on restart. May help with researching reorgs etc. [Commit](https://github.com/monero-project/monero/pull/5524). Research project by [noncesense research lab](https://noncesense-research-lab.github.io/).
| `--test-drop-download` | For net tests: in download, discard ALL blocks instead checking/saving them (very fast).
| `--test-drop-download-height` | Like test-drop-download but discards only after around certain height. By default `0`.
| `--regtest` | Run in a regression testing mode.
| `--keep-fakechain` | Don't delete any existing database when in fakechain mode.
| `--fixed-difficulty` | Fixed difficulty used for testing. By default `0`.
| `--test-dbg-lock-sleep` | Sleep time in ms, defaults to 0 (off), used to debug before/after locking mutex. Values 100 to 1000 are good for tests.
#### Legacy
These options should no longer be necessary. They are still present in `monerod` for backwards compatibility.
| Option | Description
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `--ban-list` | Specify ban list file, one IP address per line. This was introduced as an emergency measure to deal with large DDoS attacks on Monero p2p network in Dec 2020 / Jan 2021. Example: <br />`./monerod --ban-list=block.txt`. Here is the popular [block.txt](https://gui.xmr.pm/files/block.txt) file.<br /><br />It is **not recommended** to statically ban any IP addresses unless you absolutely need to. Banning IPs often excludes the most vulnerable users who are forced to operate entirely behind Tor or other anonymity networks.
| `--enable-dns-blocklist` | Similar to `--ban-list` but instead of a static file uses dynamic IP blocklist available as DNS TXT entries. The DNS blocklist is centrally managed by Monero contributors. It is **not recommended** unless in emergency situations.
| `--fluffy-blocks` | Relay compact blocks. Default. Compact block is just a header and a list of transaction IDs.
| `--no-fluffy-blocks` | Relay classic full blocks. Classic block contains all transactions.
| `--show-time-stats` | Official docs say "Show time-stats when processing blocks/txs and disk synchronization" but it does not seem to produce any output during usual blockchain synchronization.
| `--zmq-rpc-bind-ip` | IP for ZMQ RPC server to listen on. By default `127.0.0.1`. This is not yet widely used as ZMQ interface currently does not provide meaningful advantage over classic JSON-RPC interface.
| `--zmq-rpc-bind-port` | Port for ZMQ RPC server to listen on. By default `18082` for mainnet, `38082` for stagenet, and `28082` for testnet.
| `--zmq-pub` | Address for ZMQ pub - `tcp://ip:port` or `ipc://path`
| `--db-type` | Specify database type. The default and only available: `lmdb`.
## Commands
Commands give access to specific services provided by the daemon.
Commands are executed against the running daemon.
Their names follow the `command_name` pattern.
The following groups are only to make reference easier to follow.
The daemon itself does not group commands in any way.
See [running](#running) for example usage.
You can also type commands directly in the console of the running `monerod` (if not detached).
#### Help, version, status
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `help [<command>]` | Show help for `<command>`.
| `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
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `print_pl` | Show the full peer list.
| `print_pl_stats` | Show the full peer list statistics (white vs gray peers). White peers are any peers your node has completed a handshake with. Grey nodes are nodes that your node hasn't tried to connect to yet.
| `print_cn` | Show connected peers with connection initiative (incoming/outgoing) and other stats.
| `ban <IP> [<seconds>]` | Ban a given `<IP>` for a given amount of `<seconds>`. By default the ban is for 24h. Example:<br />`./monerod ban 187.63.135.161`.
| `unban <IP>` | Unban a given `<IP>`.
| `bans` | Show the currently banned IPs. Example output:<br />`187.63.135.161 banned for 86397 seconds`.
| `in_peers <max_number>` | Set the <max_number> of incoming connections from other peers.
| `out_peers <max_number>` | Set the <max_number> of outgoing connections to other peers.
| `limit [<kB/s>]` | Get or set the download and upload limit.
| `limit_down [<kB/s>]` | Get or set the download limit.
| `limit_up [<kB/s>]` | Get or set the upload limit.
#### Transaction pool
| Option | Description
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `flush_txpool [<txid>]` | Flush specified transaction from transactions pool, or flush the whole transactions pool if <txid> was not provided.
| `print_pool` | Print the transaction pool using a verbose format.
| `print_pool_sh` | Print the transaction pool using a short format.
| `print_pool_stats` | Print the transaction pool's statistics (number of transactions, memory size, fees, double spend attempts etc).
#### Transactions
| Option | Description
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `print_coinbase_tx_sum <start_height> [<block_count>]` | Show a sum of all emitted coins and paid fees within specified range. Example:<br />`./monerod print_coinbase_tx_sum 0 1000000000000`
| `print_tx <transaction_hash> [+hex] [+json]` | Show specified transaction as JSON and/or HEX.
| `relay_tx <txid>` | Force relaying the transaction. Useful if you want to rebroadcast the transaction for any reason or if transaction was previously created with "do_not_relay":true.
#### Blockchain
| Option | Description
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `print_height` | Show local blockchain height.
| `sync_info` | Show blockchain sync progress and connected peers along with download / upload stats.
| `print_bc <begin_height> [<end_height>]` | Show blocks in range `<begin_height>`..`<end_height>`. The information will include block id, height, timestamp, version, size, weight, number of non-coinbase transactions, difficulty, nonce, and reward.
| `print_block <block_hash> | <block_height>` | Show detailed data of specified block.
| `hard_fork_info` | Show current consensus version and future hard fork block height, if any.
| `is_key_image_spent <key_image>` | Check if specified [key image](/cryptography/asymmetric/key-image/) is spent. Key image is a hash.
#### Manage daemon
| Option | Description
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `exit`, `stop_daemon` | Ask daemon to exit gracefully. The `exit` and `stop_daemon` are identical (one is alias of the other).
| `set_log <level>|<{+,-,}categories>` | Set the current log level/categories where `<level>` is a number 0-4.
| `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
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `show_hr` | Ask `monerod` daemon to print current hash rate. Relevant only if `monerod` is mining.
| `hide_hr` | Ask `monerod` daemon to stop printing current hash rate. Relevant only if `monerod` is mining.
| `start_mining <addr> [<threads>] [do_background_mining] [ignore_battery]` | Ask `monerod`daemon to start mining. Block reward will go to `<addr>`.
| `stop_mining` | Ask `monerod` daemon to stop mining.
#### Testing Monero itself
| Option | Description
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `start_save_graph` | Start saving data for dr Monero.
| `stop_save_graph` | Stop saving data for dr Monero.
#### Legacy
| Option | Description
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------
| `save` | Flush blockchain data to disk. This is normally no longer necessary as `monerod` saves the blockchain automatically on exit.
| `output_histogram [@<amount>] <min_count> [<max_count>]` | Show number of outputs for each amount denomination. This was only relevant in the pre-RingCT era. The old wallet used this to determine which outputs can be used for the requested mixin. With RingCT denominations are irrelevant as amounts are hidden. More info in [these SA answers](https://monero.stackexchange.com/search?q=%22output_histogram%22).

121
interacting/overview.md
View File

@@ -1,121 +0,0 @@
---
title: Interacting with Monero
has_children: true
---
# Interacting with Monero
You can interact with Monero via desktop GUI, commandline interface, and programming API.
On top of that, Monero nodes interact with each other in a peer-to-peer network.
## Installation directory overview
Once unpacked you will see several executable files. You will also find a nice PDF guide for the GUI wallet.
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.17.1.9
# ---- guide to Monero GUI ----
monero-gui-wallet-guide.pdf
# ---- main executable files -----------
monerod
monero-wallet-gui
# ---- extra executable files -----------
extras/monero-wallet-cli
extras/monero-wallet-rpc
extras/monero-blockchain-prune
extras/monero-gen-trusted-multisig
extras/monero-gen-ssl-cert
extras/monero-blockchain-export
extras/monero-blockchain-import
# ---- don't bother with these ----------
extras/monero-blockchain-stats
extras/monero-blockchain-mark-spent-outputs
extras/monero-blockchain-prune-known-spent-data
extras/monero-blockchain-usage
extras/monero-blockchain-ancestry
extras/monero-blockchain-depth
```
## Executables
| Executable | Description
| -------------------------- |:-----------------------------------------------------------------------------------------------------------------------------------
| `monerod` | The full node daemon. Does not require a wallet. <br />[Documentation](/interacting/monerod).
| `monero-wallet-gui` | Wallet logic and __graphical__ user interface. <br />Requires `monerod` running.
| `monero-wallet-cli` | Wallet logic and __commandline__ user interface. <br />Requires `monerod` running.
| `monero-wallet-rpc` | Wallet logic and __HTTP API__ (JSON-RPC protocol). <br />Requires `monerod` running.
| `monero-blockchain-prune` | Prune existing local blockchain. This saves 2/3 of disk space (down to 31GB as of Jan 2021). This is preferable over `monerod --prune-blockchain` which only logically releases space inside the file while the file remains large. The `monero-blockchain-prune` creates a shrinked copy of the blockchain file. See [tutorial1](https://monero.stackexchange.com/questions/11454/how-do-i-utilize-blockchain-pruning-in-the-gui-monero-wallet-gui), [tutorial2](https://www.publish0x.com/solareclipse/howto-prune-shrink-the-database-of-the-monero-blockchain-on-xpgwjx).
| `monero-gen-ssl-cert` | Generate 4096 bit RSA private key and self signed TLS certificate for use with `monerod` RPC interface. Note, Monero daemon automatically generates TLS certificate on each restart. Manual generation with this tool is only useful if you want to pin TLS certificate fingerprint in your monero wallet. See the [pull request](https://github.com/monero-project/monero/pull/5495).
| `monero-gen-trusted-multisig` | Tool to generate a set of multisig wallets. <br />See chapter on [multisignatures](/multisignature).
| `monero-blockchain-export` | Tool to export blockchain to `blockchain.raw` file.
| `monero-blockchain-import` | Tool to import [blockchain.raw](https://downloads.getmonero.org/blockchain.raw) - ideally your own trusted copy.
## Executables - legacy
You most likely should not bother with these legacy or very specialized tools.
| Executable | Description
| -------------------------- |:-----------------------------------------------------------------------------------------------------------------------------------
| `monero-blockchain-stats` | Generate stats like tx/day, blocks/day, bytes/day based on your local blockchain.
| `monero-blockchain-mark-spent-outputs` | Advanced tool to mitigate potential privacy issues related to Monero forks. You normally shouldn't be concerned with that.<br />See the [commit](https://github.com/monero-project/monero/commit/df6fad4c627b99a5c3e2b91b69a0a1cc77c4be14#diff-0410fba131d9a7024ed4dcf9fb4a4e07) and [pull request](https://github.com/monero-project/monero/pull/3322).
| `monero-blockchain-prune-known-spent-data` | Previous limited pruning tool to prune select "known spent" transaction outputs (from the before RCT era). Nowadays prefer `monero-blockchain-prune`. This only saves ~200 MB. See the [commit](https://github.com/monero-project/monero/commit/d855f9bb92dbfab707a0e37505906366de818a14).
| `monero-blockchain-usage` | Advanced tool to mitigate potential privacy issues related to Monero forks. You normally shouldn't be concerned with that.<br />See the [commit](https://github.com/monero-project/monero/commit/0590f62ab64cf023d397b995072035986931a6b4) and the [pull request](https://github.com/monero-project/monero/pull/3322).
| `monero-blockchain-ancestry` | Advanced research tool to learn ancestors of a transaction, block or chain. Irrelevant for normal users. See this [pull request](https://github.com/monero-project/monero/pull/4147/files).
| `monero-blockchain-depth` | Advanced research tool to learn depth of a transaction, block or chain. Irrelevant for normal users. See this [commit](https://github.com/monero-project/monero/commit/289880d82d3cb206a2cf4ae67d2deacdab43d4f4#diff-34abcc1a0c100efb273bf36fb95ebfa0).
## Interacting
There are quite a few ways you can interact with Monero software.
Perhaps the most surprising for newcomers is that `monerod` daemon accepts interactive keyboard commands while it is running.
Also, please note that HTTP API is split across `monerod` and `monero-wallet-rpc`. You need to run and call both daemons to explore the full API.
This follows the node-logic vs wallet-logic split mentioned earlier.
All wallet implementations depend on the `monerod` running.
| Executable | p2p network | node commands via keyboard | node HTTP API | wallet commands via keyboard | wallet HTTP API | wallet via GUI
| -------------------------- | ------------------- | -------------------------- | ------------- | ---------------------------- | --------------- | --------------
| `monerod` | ✔ | ✔ | ✔ | | |
| `monero-wallet-cli` | | | | ✔ | |
| `monero-wallet-rpc` | | | | | ✔ |
| `monero-wallet-gui` | | | | | | ✔
## Data directory
This is where the blockchain, log files, and p2p network memory are stored.
By default data directory is at:
* `$HOME/.bitmonero/` on Linux and macOS
* `C:\ProgramData\bitmonero\` on Windows
Please mind:
* data directory is hidden as per OS convention
* the `bitmonero` directory name is historical artefact from before Monero forked away from Bitmonero, about 2000 years Before Christ
Data directory contains:
* `lmdb/` - the blockchain database directory
* `p2pstate.bin` - saved memory of discovered and rated peers
* `bitmonero.log` - log file
It can also contain subdirectories for stagenet and testnet, mirroring the same structure:
* `stagenet/` - data directory for Stagenet
* `testnet/` - data directory for Testnet

71
interacting/verify-monero-binaries.md
View File

@@ -1,71 +0,0 @@
---
title: Verifying Monero Binaries Signature
parent: Interacting with Monero
---
# Verify Monero Binaries
Verification must be carried on **before extracting the archive and before using Monero**.
Instructions were tested on Linux. They should also work on macOS with slight modifications.
## 1. Import lead maintainer PGP key
This is a one time action. Skip this step for subsequent Monero releases.
Monero core developers sign a list of hashes of released binaries.
BinaryFate is Monero core developer who signs the releases.
His public key is available on GitHub in the project source code.
Import binaryFate's public key to your keyring:
`curl https://raw.githubusercontent.com/monero-project/monero/master/utils/gpg_keys/binaryfate.asc | gpg --import`
Trust binaryFate's public key (fingerprint must be exactly this):
gpg --edit-key '81AC591FE9C4B65C5806AFC3F0AF4D462A0BDF92'
trust
4
{: .warning}
> 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).
## 2. Verify signature of hash list (hashes.txt)
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!
To verify these are real hashes (not tampered with) run:
`curl https://www.getmonero.org/downloads/hashes.txt | gpg --verify`
The expected output should contain the line:
`gpg: Good signature from "binaryFate <binaryfate@getmonero.org>"`
## 3. Verify the hash
By this step we checked that published hashes were not tampered with.
The last step is to compare published hash with downloaded archive SHA-256 hash.
[Download Monero](/interacting/download-monero-binaries) if you didn't already (but do not unpack).
Replace the example file name with actual one:
file_name=monero-gui-linux-x64-v0.17.1.9.tar.bz2
file_hash=`sha256sum $file_name | cut -c 1-64`
curl https://www.getmonero.org/downloads/hashes.txt > /tmp/reference-hashes.txt
# verify the signature (previous step is repeated here for completeness)
gpg --verify /tmp/reference-hashes.txt
# grep must print the hash (output cannot be empty)
grep $file_hash /tmp/reference-hashes.txt
{: .warning}
If the grep output is empty then double check everything because apparently the hashes don't match.
If grep printed filename and hash then everything is alright!

406
multisignature.md
View File

@@ -1,406 +0,0 @@
---
title: Multisignature
has_children: false
---
# Multisignature
In cryptocurrencies, multisig feature allows to sign a transaction with more than one private key. Funds protected with multisig can only be spent by signing with M-of-N keys.
Example use cases:
* shared account (1-of-2; both husband and wife individually have full access to their funds)
* consensus account (2-of-2; both husband and wife must agree to spend their funds)
* threshold account (2-of-3; an escrow service is involved as an independent 3rd party, to co-sign with either the seller, or with the buyer, if seller and buyer do not agree)
* secure account (2-of-3; a single owner controls all 3 keys but secures them via a different means to diversify risks)
* arbitrary threshold account (M-of-N; some cryptocurrencies provide full flexibility on the number of signers)
## Monero's multisig design
Monero doesn't directly implement multisignatures (at least not in a classical sense). Monero emulates the feature by secret splitting.
Transactions are still signed with a single spend key. The spend key is a sum of all N private keys. The rationale for such design is to decouple multisig from ring signatures.
Let's consider the 2-of-3 scheme. We have 3 participants. Each participant is granted exactly 2 private keys in a way that pairs do not repeat between participants. This way any 2 participants together have all 3 private keys required to create the private spend key.
Multi-signing is a wallet-level feature, and there is no separate multisig address type. This means there is no way to learn from the blockchain which transactions were created using multiple signatures.
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.
## Multisig wallet setup
Multisig is currently only available via the Command Line Interface (CLI). This tutorial will assume you have some familiarity with the CLI before beginning.
In this example we will use a 2-of-3 multisig scheme, as it generalizes well.
Initially, while you're becoming familiar with multisig, it's suggested you begin by using **stagenet**, such that no valuable Monero are lost.
If you're not already familiar with stagenet, it is a separate, but functionally identical instance of the Monero network, created for testing purposes. To use it you simply add the --stagenet flag when creating and running your stagenet wallet.
### 1: Create a new wallet
To begin you will need to create a new wallet. Multisig cannot be applied to a wallet that has previously received funds.
First you create a new wallet. The below the code assumes you're using a remote node, but using a local node is ideal:
```
./monero-wallet-cli --stagenet --daemon-address address-URL # Create your wallet
```
In the above, replace address-URL with the actual URL that you want to connect to. At the time of writing, a list of remote nodes can be found at: [monero.fail](https://monero.fail). The default view shows mainnet servers, so make sure to filter by stagenet servers first.
Next, **enable** multisig via:
```
set enable-multisig-experimental 1
```
If you don't set this flag, then try to issue the first command, you will see:
```
Error: Multisig is disabled.
Error: Multisig is an experimental feature and may have bugs. Things that could go wrong include: funds sent to a multisig wallet can't be spent at all, can only be spent with the participation of a malicious group member, or can be stolen by a malicious group member.
Error: You can enable it with:
Error: set enable-multisig-experimental 1
```
This warning message is there to let people know that Multisig is still an experimental feature and may have bugs. You can [read more](#warning) about this message below.
**Recommendation:** By default the CLI applies a screen timeout of 90 seconds. After which, you will be asked to input your password to continue using the wallet. Unfortunately, once the wallet times out, it interrupts the multisig creation process.
To extend the timeout to 10 minutes, use the command:
```
set inactivity-lock-timeout 600
```
To disable the timeout entirely (for this session only), use the command:
```
set inactivity-lock-timeout 0
```
### 2: prepare_multisig
To begin, every participant independently generates **initialization data**, which is **not** an address.
Participants then send their initialization data manually to all other participants over a secure channel.
However, if you're creating the multisig wallet without external participants, then you simply transfer the data between terminal windows.
Begin by using the command:
```
prepare_multisig
```
**Note:** if you try to use this command on a wallet that has already been used, you will see the error message:
```
Error: This wallet has been used before, please use a new wallet to create a multisig wallet
```
After prepare_multisig you will see a message that looks similar to the below:
```
MultisigxV2R1C9Bd2LNS9oDXLwDWbVbWc53nfUJpFnQqPDDtHksVVrY33DADgnhKetL5Swgk477uP1AENAy2pz11zW73NGqZojTai2TSDyARK3QR8uVt1t26oW21mFdZtd8iuNqTPBjuCc2q9jaRzqUG75rXtnn8eD5DwJX6NaMP63o2n2fta7dXZcpM
Send this multisig info to all other participants, then use make_multisig <threshold> <info1> [<info2>...] with others' multisig info
This includes the PRIVATE view key, so needs to be disclosed only to that multisig wallet's participants
```
The long string that begins Multisig is important, and will be shared with the other wallets in the next step.
Before you move to the next step, you'll want to run the **prepare_multisig** command on the rest of the wallets you want to use in your multisig setup. For example, 2 more if you're doing a 2/3 multisig.
### 3: make_multisig
This command is where you set the threshold for your multisig wallet and then pass the initialization data from the other participants. The initialization data is the long string beginning **Multisig** mentioned above.
For example, if you're doing a 2 of 2 multisig, then your threshold is 2 and you'll pass 1 piece of data. If you're doing a 3 of 5 multisig, then your threshold is 3 and you'll pass 4 pieces of data.
Continuing with our 2/3 multisig example, you would then type into your CLI:
```
make_multisig 2 <data1> <data2>
```
Which in practice would look similar to:
```
make_multisig 2 MultisigxV2R1MyhE1hgED7AFwytsfW44s7G4abNHFKhwfJH9kvB2Q7xNVBdJAyY9gm7eJkHVRo1T3Hb6PeYsyzUrqQsmpBByDq4iRywanpRLxLN2JKuvKPBDayAywAHBzGxdnGiyoXhLdnZiU6Azy3VNocwH1jgfFvYDUUCo7H8mFacnLUFVLC8LjEfz MultisigxV2R1CzwgGBTPxb51nWfvLg7mYPRBnqDgppZq85E745qR1NvGNCLBaHSCmUQ4JRb41tW9PUerAgz9pKHJ5NpKgE6vsZnpLJkCP3u4zwcXJW3UHjABc446jdQegP1hyHnGgJpah8RmdeLcLCAqa6WXgt3xJoz6QF5o66tnCiyJkYyebjWeXV2y
```
If you were doing a 3/5 multisig, you'd instead run:
```
make_multisig 3 <data1> <data2> <data3> <data4>
```
Once this command is run on each wallet, you will then receive a second round of initialization data, that looks similar to:
```
Another step is needed
MultisigxV2Rn1LVYohry597ZfzPhWnuL6qcueBNdq4ivrP7zqDm4W5eKBhxgdcERcSvFs8F5EkLSuYFyKfBEeh4Fui6xHTeRqb7cWshXY96WruxMaSxMafTdPn48ko52e8UHvA4kWwpuPidBYg5dyVWoQLWgqCMDANxWnjhenw6HTwpT96yB8n1a16oQEYyQWg66r2sZHi9RMmivTsihnMq66rTHKPKKau1SHButDwQ
```
**Side note:** If you make a mistake, such as inputting the wrong threshold or missing out some initialization data, there isn't an undo function. That individual wallet will get created incorrectly, and you will need to re-do it.
### 4: exchange_multisig_keys
With the threshold established in the prior command, the exchange_multisig_keys command simply takes the init data from the other participants, no threshold parameter needed.
For example:
```
exchange_multisig_keys <data1> <data2>
```
It is either run once or twice in total.
Once if your wallet has the same threshold as the total number of participants, e.g. 2 of 2.
Twice if you have a different threshold, e.g. 2 of 3.
Continuing our 2/3 multisig example, after inputting the above exchange_multisig_keys command, we would then see:
```
Another step is needed
MultisigxV2Rn1WCSNqbsjuTXaPVfFsk3ekFF444yFN5PMCXcQHv1Pv794ZdkDZRnfVGgeP5JwpysR3ingQtQMMnmQDEXnP4qgdnh3SU2NXvfe7kMaSxMafTdPn48ko52e8UHvA4kWwpuPidBYg5JdJwdEAh8Ud7kBFX34zP33ZBbrYXcQbQKTcM3XQ8AEP8bVXHVqQSGzkAkjZRp3H63k6ZSXSYdH9WaC9pdr9FV3tx
Send this multisig info to all other participants, then use exchange_multisig_keys <info1> [<info2>...] with others' multisig info
```
Then for a second, and last time, we input:
```
exchange_multisig_keys <data1> <data2>
```
And we receive back:
```
Multisig wallet has been successfully created. Current wallet type: 2/3
Multisig address: 56MD1L4zky3bFXDQb9qvSx7PDbg8F4x1HgPrFNrDnGnYDqFZcWGswWc1p2moFa1F44ccJniY9Wkzk6urkJbEDvubHqYtkcs
```
This results in a wallet **public address** and **private view key** to be known for all participants.
So if you're the sole participant in the multisig setup, you'll know it has worked when you see the same multisig address across all the wallets.
## Receiving funds
### 1: Funding the Multisig Account
Addresses created by a multisig wallet operate the same as normal, non-multisig addresses. This means:
- Each wallet can create subaddresses independently, no collaboration needed.
- All participants can see incoming funds as they share the private view key.
The main difference comes when trying to spend funds from a multisig wallet. See the **Spending Funds** section below for how to do this.
### 2: Check Account Balance
To check the account balance, open one of the multisig wallets and type the **refresh** command.
This will refresh the wallet and display your balance. The output will look similar to the below, but with a different amount:
```
Starting refresh...
Refresh done, blocks received: 0
Currently selected account: [0] Primary account
Tag: (No tag assigned)
Balance: 10.000000000000, unlocked balance: 10.000000000000 (Some owned outputs have partial key images - import_multisig_info needed)
```
If you see that last sentence:
```
(Some owned outputs have partial key images - import_multisig_info needed)
```
This means that you haven't synchronized your wallet with the threshold amount of wallets needed (1 other in the case of 2/3 multisig) for the outputs to become spendable.
You can also use the command **show_transfers** to display a list of funds received and the transfer date, with the output looking similar to:
```
1263592 in unlocked 2023-01-09 21:13:59 10.000000000000 c5a3eec347401b1e263f45577b840c036568aa841eb2ebc6eb1332c1bc281f28 0000000000000000 0.000000000000 76Matb:10.000000000000 1 -
```
## Spending funds
Prior to explaining the process for spending multisig funds, it may help to have a high level overview of the process. There are two core steps:
1) **First, the sharing of partial key-images** - At minimum, the spender needs to get a partial key image from the people (1 or more) who will sign the transaction with him later. They need to export a file and share it with the future spender, who then imports the file to their wallet.
2) **Second, creating, signing & submitting the transaction** - A transfer is created, written to file, and then this file needs to be signed by the co-signers, before it can lastly be submitted to the network.
### Preparation for spending
**Preparation Step 1: Export partial key image**
Prior to constructing a transaction, the spender will need to get a partial key image from the wallet or wallet**s** which will later co-sign the transaction.
In our 2/3 multisig example, the spender needs to get 1 partial key image, because the threshold is 2.
The wallet that will provide the partial key image needs to enter the command:
```
export_multisig_info key1
```
Where **key1** can be any filename. The output will then be:
```
Multisig info exported to key1
```
The file will be saved to the present working directory in the terminal.
It then needs to be shared with the wallet which will create the spending transaction.
**Preparation Step 2: Import partial key image**
Now that the spending wallet has the partial key image it can import it. Assuming the file is in the present working directory, the command would be:
```
import_multisig_info key1
```
If two or more key images were being imported, you would specify them side by side, such as:
```
import_multisig_info key1 key2 key3
```
After issuing that command, the wallet will display how many new inputs it has verified, for example if 1 output is verified:
```
Height 1263592, txid <c5a3eec347401b1e263f45577b840c036568aa841eb2ebc6eb1332c1bc281f28>, 10.000000000000, idx 0/1
Multisig info imported. Number of outputs updated: 1
```
### Spending
**Spending Step 1 - Create Unsigned Transaction**
Creating a new transaction can be done by **any** of the multisig wallets. However, to avoid weird things from happening, only do it for 1 transaction at a time. If anything weird happens, re-do steps 1 & 2 again to fix.
The wallet initiating the transfer should create a transfer, as per the normal CLI transfer process:
```
transfer <address> <amount>
```
So for example:
```
[wallet 56MD1L]: transfer 72Qv1pqug5rX1qS77Bj9C4XBbrvdYRJLM6769bseDytqVZWV2iQxGDnZ85KmubdiCQgtZjeb4fPdUNGq8Foae5b1Bo77T64 5
Wallet password:
Transaction 1/1:
Spending from address index 1
Sending 5.000000000000. The transaction fee is 0.000167640000
Is this okay? (Y/Yes/N/No): Yes
```
The output will look like:
```
Unsigned transaction(s) successfully written to file: multisig_monero_tx
```
The present working directory will now contain a file named **multisig_monero_tx**, which should then be shared with the co-signer.
**Spending Step 2 - Sign Transaction**
The wallet that has been chosen to co-sign the transaction now needs to run the command:
```
sign_multisig multisig_monero_tx
```
Which will result in an output similar to:
```
Loaded 1 transactions, for 10.000000000000, fee 0.000167640000, sending 5.000000000000 to 72Qv1pqug5rX1qS77Bj9C4XBbrvdYRJLM6769bseDytqVZWV2iQxGDnZ85KmubdiCQgtZjeb4fPdUNGq8Foae5b1Bo77T64, 4.999832360000 change to 56MD1L4zky3bFXDQb9qvSx7PDbg8F4x1HgPrFNrDnGnYDqFZcWGswWc1p2moFa1F44ccJniY9Wkzk6urkJbEDvubHqYtkcs, with min ring size 16, dummy encrypted payment ID. Is this okay? (Y/Yes/N/No): y
Transaction successfully signed to file multisig_monero_tx, txid 82132a4302188b15c87916c05df79755dafb9ada78c39164937c246a4c2dee0a
It may be relayed to the network with submit_multisig
```
**Note:**
Once you synchronize the partial key images, there is a certain time window by which you can create and send your transaction. I'm unsure exactly how long the time window is. If you leave it too long you will see the output:
```
Error: Multisig error: This signature was made with stale data: export fresh multisig data, which other participants must then use
```
The solution is to re-do steps 1 and 2 of the preparation for sending. Once that's completed, you can return to the sending steps.
**Spending Step 3 - Submit Transaction**
Now that your transaction has been co-signed, it is possible to submit it. You can do this from any of the wallets, as long as they have the co-signed multisig_monero_tx file. Using the command:
```
submit_multisig multisig_monero_tx
```
You will then see an output similar to:
```
[wallet 56MD1L]: submit_multisig multisig_monero_tx
Wallet password:
Loaded 1 transactions, for 10.000000000000, fee 0.000167640000, sending 5.000000000000 to 72Qv1pqug5rX1qS77Bj9C4XBbrvdYRJLM6769bseDytqVZWV2iQxGDnZ85KmubdiCQgtZjeb4fPdUNGq8Foae5b1Bo77T64, 4.999832360000 change to 56MD1L4zky3bFXDQb9qvSx7PDbg8F4x1HgPrFNrDnGnYDqFZcWGswWc1p2moFa1F44ccJniY9Wkzk6urkJbEDvubHqYtkcs, with min ring size 16, dummy encrypted payment ID. Is this okay? (Y/Yes/N/No): y
Transaction successfully submitted, transaction <82132a4302188b15c87916c05df79755dafb9ada78c39164937c246a4c2dee0a>
You can check its status by using the `show_transfers` command.
```
The transaction has now been broadcast to the network. If you want to create another one, you will need to go back to the preparation stage and re-sync the partial key images.
## Mnemonic Seeds
With a regular wallet is it possible to create a mnemonic seed that you can backup, and later use to recreate the wallet.
Fortunately, multisig wallets have the same feature. The only difference is that the seed is a **long string** of letters and numbers, rather than a set of dictionary words. Unfortunately, it needs to encode too much data to fit neatly into the regular mnemonic seed dictionary output.
To access your wallet seed, open the wallet within the CLI and type **seed**. You will see an output similar to this:
```
NOTE: the following string can be used to recover access to your wallet. Write them down and store them somewhere safe and secure. Please do not store them in your email or on file storage services outside of your immediate control.
020000000300000051512b513c603a023df44e2400ad58b3f4751e2dcba44b1d4316be5adffd330b773b3818a07ab6ccc4ffcee1feed5526296b52f5ea0844eb8562cb3e63e8154c5c91f0cfd102a830d8692cec64e662f7ffac4cb82dd950c891a92a22dc80930ab78dd01a1ec7ed04d90eff530d2af9d4e40670576863492357727c6615620e95d2e962632518d958040b710474a4c944cb3a286e3fe9ad0b1d651ff6d8b4c50c81a74423650210bbcb7b427435e90b3eb494cb108bd148cab56e5352303d55070d35e703217b7b051a96af50c1c912bc372f65a4ffa93631ae009a544106bd5dfcf477573387f159ce6cae10fb2ffe63f55e75ed94d0893ece9b67b0a1cf0fc2034ca04ef7c862494a13237bfaa8e822f824ea59de561353f2ac01fbc279280c
```
**Note:** This seed will only recreate the individual wallet it is created from. Each wallet would need to be backed up separately.
## <a id="warning"></a>About the experimental feature warning message
Prior to a pull request in mid 2022 ([PR #8149](https://github.com/monero-project/monero/pull/8149)) Monero's multisig feature had some known bugs.
PR #8149 fixed these issues, including findings identified by an [independent audit](https://github.com/monero-project/monero/pull/8149#issuecomment-1167912258) of multisig.
However, there is still a possibility of a yet **unknown** bug that would allow a malicious group member, in a worst-case scenario, to acquire all funds within the multisig wallet.
Two potential steps to get Monero's multisig implementation further tested and more secure would be the completion of a formal specification and a third-party audit. However, there is currently no timeline for this.
It's worth noting that the risks implied by this unknown bug scenario depend upon the individual use-case. For example:
a) If one planned to use multisig in collaboration with other people, then this risk is there.
b) If one planned to use multisig solely to shard a cold wallet, and store it in multiple locations, then this risk may be lessened. On the basis that it requires two coincidences to come together:
i) A malicious actor who has the capability to exploit an unknown bug in Monero's multisig.
ii) This malicious actor is then able to access one of the, presumably secured, multisig wallets.
However, if an exploit was made public knowledge, then the risk increases, because the attacker no longer needs to figure out the exploit, they simply need to locate your wallet and then implement the public exploit.
Thus, if one took the risk to use multisig in method b), they would be prudent to stay up to date on multisig development. Such that they would learn quickly if such an exploit was discovered.
## References
The below guides are very detailed, and were formative in the creation of this document. Note that they are both a little out of date, as a few of the CLI commands have been updated in the interim.
* [https://monero.stackexchange.com/questions/5646/how-to-use-monero-multisignature-wallets-2-2-2-3](https://monero.stackexchange.com/questions/5646/how-to-use-monero-multisignature-wallets-2-2-2-3)
* [https://taiga.getmonero.org/project/rbrunner7-really-simple-multisig-transactions/wiki/23-multisig-in-cli-wallet](https://taiga.getmonero.org/project/rbrunner7-really-simple-multisig-transactions/wiki/23-multisig-in-cli-wallet)

42
proof-of-work/pow-in-cryptocurrencies.md
View File

@@ -1,42 +0,0 @@
---
title: Proof of Work in Cryptocurrencies
parent: Proof of Work
---
# Proof of Work in Cryptocurrencies
> Proof of work is a Sybil protection mechanism
## PoW protects against Sybil attack
In decentralized cryptocurrencies **untrusted** actors confirm (blocks of) transactions.
If threshold voting was employed then the scheme would break immediately.
This is because nothing prevents a single actor from creating arbitrary number of pseudonyms and take over the voting.
In distributed systems this is known as Sybil attack.
Instead, cryptocurrencies employ proof of work. In the proof of work scheme,
it is not the number of actors that counts. It is the amount of committed
computational resources.
This, of course, is much harder to game.
To endanger the scheme, an attacker would have to actually control majority (>50%) of computational resources.
In practice, attacker would need this control over significant period of time.
## PoW is a leader election mechanism
In distributed systems "leader election" is a process of establishing which node is responsible for (temporarily) coordinating the system.
In cryptocurrencies PoW is used to elect the node that "wins" the next block.
Using PoW for leader election was one of the key inventions introduced by Bitcoin.
Competing nodes (known as "miners") work on a solution to artificial problem.
Every now and then, someone randomly finds the solution.
Chances are linearly proportional to committed computing power.
The winner uses its solution to "underwrite" the block it assembled. Only blocks with valid solutions are accepted by the network.
The winner also gets a reward for its work. The reward is a specific amount of cryptocurrency created "out of thin air" and assigned to self. The winner also gets all fees coming from transactions included in the block.
The difficulty of the PoW problem is dynamically adjusted by the network, with the goal of finding blocks with a roughly constant rate (typically, every couple of minutes).

4
proof-of-work/proof-of-work.md
View File

@@ -1,4 +0,0 @@
---
title: Proof of Work
has_children: true
---

8
proof-of-work/random-x.md
View File

@@ -1,8 +0,0 @@
---
title: RandomX
parent: Proof of Work
---
# RandomX
For general information about RandomX you can read this [article](https://www.monerooutreach.org/stories/RandomX.html).

41
proof-of-work/what-is-pow.md
View File

@@ -1,41 +0,0 @@
---
title: About Proof of Work (General)
parent: Proof of Work
---
# About Proof of Work (General)
> Proof of work is a way to legitimize untrusted party
### What exactly is proof of work?
Proof of work is a cryptographic proof that untrusted party committed significant computational resources to solve artificial problem.
Technically, the "proof" is simply a solution to the problem at hand.
### It's all about legitimizing untrusted party
How an untrusted party on the Internet could earn any level of your trust?
It can prove its commitment by solving agreed computationally hard problem.
For example, by requiring untrusted party to perform a hard computation before you accept their connection, you limit connections only to "committed" parties.
In another example, you could require PoW to be attached to incoming e-mails to make spam prohibitively expensive.
### Work must be otherwise useless
The work on and solution to "computationally hard problem" cannot be useful in any other way than to prove the commitment.
If the work is useful elsewhere then it doesn't prove commitment to you.
The problem must be artificial. Otherwise incentives are skewed and the whole scheme breaks.
### Strong asymmetry
The requirement for proof of work scheme is strong asymmetry for work vs verification resources.
The work must be arbitrarily hard. At the same time proof verification must remain dirt cheap (in terms of computational resources).
Cheap verification is critical because at this stage we are dealing with potentially huge number of untrusted parties,
who could DoS the verifier by submitting invalid proofs. Such proofs should be trivial to discard.

6
public-address/main-address.md
View File

@@ -1,6 +0,0 @@
---
layout: redirected
sitemap: false
permalink: /public-address/main-address/
redirect_to: /public-address/standard-address/
---

4
public-address/public-address.md
View File

@@ -1,4 +0,0 @@
---
title: Public Address
has_children: true
---

96
public-address/standard-address.md
View File

@@ -1,96 +0,0 @@
---
title: Standard Address
parent: Public 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:
* 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](/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
### Generating the keys
As mentioned above, a Monero address encodes two elliptic curve public keys so the first step is to generate two elliptic curve private keys from which the public keys may be derived.
Each private key is represented by a scalar between 1 and 2^252 + 27742317777372353535851937790883648492 inclusive. (Note: 2^252 + 27742317777372353535851937790883648492 + 1 is a prime order of the elliptic curve basepoint, `l`).
To generate a new private key, the convention is to generate a random 256 bit numbers and reduce it modulo 2^252 + 27742317777372353535851937790883648493.
To get the public keys to be encoded in the address, the ed25519 basepoint `G` is multiplied by each key scalar.
### Checksum
A checksum of the network byte and public keys is included in the address to help wallet software verify that a typo hasn't been made when users enter the address.
To get this checksum, the network byte as well as the public spend and view keys are concatenated together and Keccak-256 hashed. The first four bytes of this hash are the checksum.
When wallet software parses a Monero address it should decode the address and recompute the checksum and verify that it matches the checksum included in the address.
### Base58 Encoding
In an effort to further prevent errors from typos Monero addresses are encoded using a special character dictionary.
Characters used in Monero base58: `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`. Notice how characters that look similar such as `O` and `0` are missing.
[More about Monero base58](/cryptography/base58).
### Deteministic Wallets
There is no way to regulate how people choose their address keys, it is simply highly suggested that they are chosen at random. The original CryptoNote implementation generated each keypair randomly, independently of each other. Addresses generated this way are called non-deterministic, they have fallen out of popularity.
As of present, the convention is to derive an address's view key deterministically from the spend key which allows for human language encoded seed mnemonics.
Deterministic addresses derive the private view key from the private spend key by hashing it (conventionally Keccak-256) and reducing it modulo `l`.
## 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)
* [src/cryptonote_basic/account.cpp account_base::generate](https://github.com/monero-project/monero/blob/dcba757dd283a3396120f0df90fe746e3ec02292/src/cryptonote_basic/account.cpp#L155)

131
public-address/subaddress.md
View File

@@ -1,131 +0,0 @@
---
title: Subaddress
parent: Public Address
---
# Subaddress
Subaddress is what you should be using by default to receive Monero.
## Learn for what you are being paid
By providing a unique subaddress for each anticipated payment you will know for what you are being paid.
This use case overlaps with integrated addresses. Subaddresses are generally prefered for reasons outlined below.
## Prevent payer from linking your payouts together
To prevent the payer from linking your payouts together simply generate a new subaddress for each payout.
This way specific service (like anonymous exchange) that sends you Monero won't (easilly) know it is you again receving Monero.
The exception to this is when a service (or group of colluding services) decides to actively attack you, one address at the time, with the so-called [Janus attack](https://web.getmonero.org/2019/10/18/subaddress-janus.html), which risks them losing funds. If you need perfect unlinkability of your receivables, the only solution remains to use a separate seed (separate Monero wallet).
Also, note it won't help if you have an account with the service. Then your payouts are already linked in the service database, regardless of Monero.
## Group funds into accounts
**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.
As accounts are only groupings of subaddresses, they themselves do not have an address.
Accounts are deterministically derived from the root private key along with subaddresses.
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.
## Why not multiple wallets?
The advantage over creating multiple wallets is that you only have a **single seed** to manage.
All subaddresses can be derived from the wallet seed.
Additionally, you conveniently manage your subaddresses within a single user interface.
## Wallet level feature
Subaddresses and accounts are a wallet-level feature to construct and interpret transactions. They do not affect the consensus.
## Data structure
Subaddress has a dedicated "network byte":
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 [standard address](/public-address/standard-address/#data-structure).
## Generating
Each subaddress conceptually has:
* account index (also known as "major" index)
* subaddress index within the account (also known as "minor" index)
The indexes are 0-based. By default wallets use account index 0.
The indexes are not directly included in the subaddress data structure.
Instead, they are used as input to generating subaddress keys.
### Private view key
A per-subaddress scalar `m` is derived as follows:
m = Hs("SubAddr" || a || account_index || subaddress_index_within_account)
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 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)
Deriving "sub view keys" from the main view key allows for creating a view only wallet that monitors the entire wallet including subaddresses.
### Public spend key
The subaddress public spend key `D` is derived as follows:
D = B + m*G
Where:
* `B` is standard address public spend key
* `m` is a per-subaddress scalar that is derived from the private spend key
* `G` is the "base point"; this is simply a constant specific to [edwards25519](/cryptography/asymmetric/edwards25519)
### Public view key
The subaddress public view key `C` is derived as follows:
C = a*D
Where:
* `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 [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 [standard address](/public-address/standard-address).
## Caveats
* 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
* [monero-python](https://github.com/emesik/monero-python/blob/125d5eac0d4583b586b98e21b28fb9a291db26e5/monero/wallet.py#L195) - the easiest to follow implementation by Michał Sałaban
* [get_subaddress_spend_public_key()](https://github.com/monero-project/monero/blob/16dc6900fb556b61edaba5e323497e9b8c677ae2/src/device/device_default.cpp#L143) - Monero reference implementation
* [historical discussion on Github](https://github.com/monero-project/monero/pull/2056) - gives context but is not up to date with all details
* [StackExchange answer](https://monero.stackexchange.com/questions/10674/how-are-subaddresses-and-account-addresses-generated-from-master-wallet-keys/10676#10676) - excellent summary by knaccc

308
running-node/open-node-tor-onion.md
View File

@@ -1,308 +0,0 @@
---
title: Running Monero Open Node with Tor Onion Support
has_children: false
---
# Running Monero Open Node + Tor Onion
{: .success title="Powerful setup"}
This is great contribution to Monero network and also a pretty sophisticated personal setup. If you are a beginner, you don't need this.
{: .note title="The end goal"}
> You will publicly offer the following services, where xxx.yyy.zzz.vvv is your server IP address.
>
> * xxx.yyy.zzz.vvv:18080 - clearnet P2P service (for other nodes)
> * xxx.yyy.zzz.vvv:18081 - clearnet RPC service (for wallets)
> * yourlongv3onionaddress.onion:18083 - onion P2P service (for other onion nodes)
> * yourlongv3onionaddress.onion:18081 - onion RPC service (for wallets connecting over Tor)
>
> Why different P2P ports for clearnet and onion? This is a `monerod` requirement.
{: .warning title="Warning: Broadcasting bad transactions from your IP"}
As with any public data broadcast or relay service, "bad traffic" or in this case "bad transactions" may appear to originate from your server IP address from an outside observer perspective - even though they really originate from a remote wallet user. This is a potential risk you need to keep in mind.
## Why run this specific setup?
You will be able to connect your desktop and mobile Monero wallets to your own trusted Monero node,
in a secure and private way over Tor. Your node will be always ready w/o delays (always synced up, contrary to intermittently running node on a laptop).
**Serving blocks and transactions** in Monero P2P network helps new users to bootstrap and sync up their nodes.
It also strenghtens Monero P2P network against DDoS attacks and network partitioning.
**Open wallet inteface** (the "RPC") allows anyone to connect their wallets to Monero network through your node.
This is useful for beginner users who don't run their own nodes yet.
**Tor onion for wallet interface** is useful for wallet users connecting over Tor because it mitigates Tor exit nodes MiTM risks (which are very real). By connecting wallet to an onion service, no MiTM attack is realistic because within the Tor network connections are end-to-end TLS-ed.
**Tor onion for P2P network** is useful for other full node users as it allows them to broadcast transactions over Tor (using `--tx-proxy` option).
## Assumptions
You understand basic Linux administration. You seek Monero specific guidance.
You have root access to a Linux server with 2GB+ RAM and 120GB+ SSD (or 50GB+ for the pruned node version). This is current for Jan 2021.
Some commands assume Ubuntu but you will easily translate them to your distribution.
## Install Tor
[Install Tor](https://2019.www.torproject.org/debian.html.en#ubuntu).
Modify `/etc/tor/torrc` as shown below.
Enable tor service with `systemctl enable tor` and restart it via `systemctl restart tor`
Verify the Tor is up `systemctl status tor@default`
A fresh onion address and corresponding key pair got created for you by the `tor` daemon in `/var/lib/tor/monero/`. You may want to backup these to secure control over your onion address. This happens on restart whenever you add new `HiddenServiceDir` to `torrc` config.
Monero daemon itself is not necessary at this point. The onion services (AKA hidden services) will just wait until localhost `monerod` shows up at specified ports 18081 and 18083.
### /etc/tor/torrc
``` ApacheConf
HiddenServiceDir /var/lib/tor/monero
HiddenServicePort 18081 127.0.0.1:18081 # interface for wallet ("RPC")
HiddenServicePort 18083 127.0.0.1:18083 # interface for P2P network
```
??? info "How Tor onion services work?"
The `tor` daemon will simply pass over the traffic from virtual onion port to actual localhost port, where some service is listening (in our case, this will be `monerod`). A single onion address can offer multiple services at various virtual ports. We will use this to expose both P2P and RPC `monerod` services on a single onion. You could host any number of onion addresses at single server or IP address but we won't need that here.
## Install Monero
Create `monero` user and group `useradd --system monero`
Create monero **binaries** directory (empty for now) `mkdir -p /opt/monero` and `chown -R monero:monero /opt/monero`
Create monero **data** directory `mkdir -p /srv/monero` and `chown -R monero:monero /srv/monero`
Create monero **log** directory `mkdir -p /var/log/monero` and `chown -R monero:monero /var/log/monero`
Feel free to adjust above to your preferred conventions, just remember to adjust the paths accordingly.
[Download](/interacting/download-monero-binaries/) and [verify](/interacting/verify-monero-binaries/) the file.
Extract `tar -xf monero-linux-x64-v0.17.1.9.tar.bz2` (adjust filename).
Move binaries to `/opt/monero/` with `mv monero-x86_64-linux-gnu-v0.17.1.9/* /opt/monero/` then `chown -R monero:monero /opt/monero`
Create `/etc/monero.conf` as shown below and **paste your values in placeholders**.
Create `/etc/systemd/system/monero.service` as shown below.
Enable monero service with `systemctl enable monero` and restart it with `systemctl restart monero`
Verify it is up `systemctl status monero`
Verify it is working as intended `tail -n100 /var/log/monero/monero.log`
### /etc/monero.conf
This is just an example configuration and it is by no means authoritative. Feel free to modify, see [monerod reference](/interacting/monerod).
Modify paths if you changed them.
Print your onion address with `cat /var/lib/tor/monero/hostname` and paste it to `anonymous-inbound` option.
``` YAML
# /etc/monero.conf
#
# Configuration file for monerod. For all available options see the MoneroDocs:
# https://getmonero.dev/interacting/monerod/
# Data directory (blockchain db and indices)
data-dir=/srv/monero
# Optional prunning
# prune-blockchain=1 # Pruning saves 2/3 of disk space w/o degrading functionality but contributes less to the network
# sync-pruned-blocks=1 # Allow downloading pruned blocks instead of prunning them yourself
check-updates=disabled # Do not check DNS TXT records for a new version
# Log file
log-file=/var/log/monero/monero.log
log-level=0 # Minimal logs, WILL NOT log peers or wallets connecting
max-log-file-size=2147483648 # Set to 2GB to mitigate log trimming by monerod; configure logrotate instead
# P2P full node
p2p-bind-ip=0.0.0.0 # Bind to all interfaces (the default)
p2p-bind-port=18080 # Bind to default port
# RPC open node
public-node=1 # Advertise to other users they can use this node as a remote one for connecting their wallets
confirm-external-bind=1 # Open Node (confirm)
rpc-bind-ip=0.0.0.0 # Bind to all interfaces (the Open Node)
rpc-bind-port=18081 # Bind to default port (the Open Node)
restricted-rpc=1 # Obligatory for Open Node interface
no-igd=1 # Disable UPnP port mapping
no-zmq=1 # Disable ZMQ RPC server to decrease attack surface (it's not used)
# RPC TLS
rpc-ssl=autodetect # Use TLS if client wallet supports it (the default behavior); the certificate will be generated on the fly on every restart
# Mempool size
max-txpool-weight=268435456 # Maximum unconfirmed transactions pool size in bytes (here 256MB, default ~618MB)
# Slow but reliable db writes
db-sync-mode=safe
out-peers=64 # This will enable much faster sync and tx awareness; the default 8 is suboptimal nowadays
in-peers=64 # The default is unlimited; we prefer to put a cap on this
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
# Tor: broadcast transactions originating from connected wallets over Tor (does not concern relayed transactions)
tx-proxy=tor,127.0.0.1:9050,16
# Tor: add P2P seed nodes for the Tor network
# For an up-to-date list of working nodes see https://www.ditatompel.com/monero/node-peers
add-peer=4egylyolrzsk6rskorqvocipdo4tqqoyzxnplbjorns7issmgpoxvtyd.onion:18083
add-peer=fagmobguo6u4z4b2ghyg3jegcdpmd4qj4wxkhemph5d5q6dltllveqyd.onion:18083
add-peer=monerokdwzyuml7vfp73fjx5277lzesbrq4nvbl3r3t5ctgodsx34vid.onion:18089
add-peer=b75obarnhi42p7js7wgzo7v3wtiwcgf4bknrwv6ihatop77jivrtwpid.onion:15892
add-peer=5nvd6jbefgto3u74nzzdkcsbqgxyzrkk7bz5qupsdqg4gbuj5valiaqd.onion:18083
add-peer=ozeavjybjbxbvmfcpxzjcn4zklbgohjwwndzenjt44pypvx6jisy74id.onion:18083
add-peer=xcccrsxi2zknef6zl3sviasqg4xnlkh5k3xqu7ytwkpfli3huyfvsjid.onion:18083
# Make the seed nodes permanent to fix monerod issue of not maintaining enough connections,
# based on this reddit comment:
# https://www.reddit.com/r/monerosupport/comments/k3m3x2/comment/ge5ehcy/?utm_source=share&utm_medium=web2x&context=3
add-priority-node=4egylyolrzsk6rskorqvocipdo4tqqoyzxnplbjorns7issmgpoxvtyd.onion:18083
add-priority-node=fagmobguo6u4z4b2ghyg3jegcdpmd4qj4wxkhemph5d5q6dltllveqyd.onion:18083
add-priority-node=monerokdwzyuml7vfp73fjx5277lzesbrq4nvbl3r3t5ctgodsx34vid.onion:18089
add-priority-node=b75obarnhi42p7js7wgzo7v3wtiwcgf4bknrwv6ihatop77jivrtwpid.onion:15892
add-priority-node=5nvd6jbefgto3u74nzzdkcsbqgxyzrkk7bz5qupsdqg4gbuj5valiaqd.onion:18083
add-priority-node=ozeavjybjbxbvmfcpxzjcn4zklbgohjwwndzenjt44pypvx6jisy74id.onion:18083
add-priority-node=xcccrsxi2zknef6zl3sviasqg4xnlkh5k3xqu7ytwkpfli3huyfvsjid.onion:18083
# Tor: tell monerod your onion address so it can be advertised on P2P network
anonymous-inbound=PASTE_YOUR_ONION_HOSTNAME:18083,127.0.0.1:18083,64
# Tor: be forgiving to connecting wallets; suggested by http://xmrguide42y34onq.onion/remote_nodes
disable-rpc-ban=1
```
### /etc/.../monero.service
``` INI
# /etc/systemd/system/monero.service
[Unit]
Description=Monero Daemon
After=network.target
Wants=network.target
[Service]
ExecStart=/opt/monero/monerod --detach --config-file /etc/monero.conf --pidfile /run/monero/monerod.pid
ExecStartPost=/bin/sleep 0.1
Type=forking
PIDFile=/run/monero/monerod.pid
Restart=always
RestartSec=16
User=monero
Group=monero
RuntimeDirectory=monero
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
## Open firewall ports
If you use a firewall (and you should), open `18080` and `18081` ports for incoming TCP connections. These are for the incoming **clearnet** connections, P2P and RPC respectively.
You **do not** need to open any ports for Tor. The onion services work with virtual ports. The `tor` daemon does not directly accept incoming connections and so it needs no open ports.
For example, for popular ufw firewall, that would be:
``` Bash
ufw allow 18080/tcp
ufw allow 18081/tcp
```
To verify, use `ufw status`. The output should be similar to the following (the `22` being default SSH port, unrelated to Monero):
```
To Action From
-- ------ ----
22/tcp LIMIT Anywhere
18080/tcp ALLOW Anywhere
18081/tcp ALLOW Anywhere
22/tcp (v6) LIMIT Anywhere (v6)
18080/tcp (v6) ALLOW Anywhere (v6)
18081/tcp (v6) ALLOW Anywhere (v6)
```
## Testing
### On server
List all services listening on ports and make sure it is what you expect:
`sudo netstat -lntpu`
The output should include these (in any order); obviously the PID values will differ.
```
Proto Recv-Q Send-Q Local Address Foreign Address State PID/Program name
...
tcp 0 0 0.0.0.0:18080 0.0.0.0:* LISTEN 259255/monerod
tcp 0 0 0.0.0.0:18081 0.0.0.0:* LISTEN 259255/monerod
tcp 0 0 127.0.0.1:18083 0.0.0.0:* LISTEN 259255/monerod
tcp 0 0 127.0.0.1:9050 0.0.0.0:* LISTEN 258786/tor
```
### On client machine
Finally, we want to test connections from your client machine.
Install `tor` and `torsocks` on your laptop, you will want them anyway for Monero wallet.
Just for testing, you will also need `nmap` and `proxychains`.
Test **clearnet P2P** connection:
`nmap -Pn -p 18080 YOUR_IP_ADDRESS_HERE`
Test **clearnet RPC** connection:
`curl --digest -X POST http://YOUR_IP_ADDRESS_HERE:18081/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_info"}' -H 'Content-Type: application/json'`
Test **onion P2P** connection (skip if you don't have proxychains):
`proxychains nmap -Pn -p 18083 YOUR_ONION_ADDRESS_HERE.onion`
Test **onion RPC** connection:
`torsocks curl --digest -X POST http://YOUR_ONION_ADDRESS_HERE.onion:18081/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_info"}' -H 'Content-Type: application/json'`
## Debugging
Tor:
* Status: `systemctl status tor@default`
* Logs: `journalctl -xe --unit tor@default`
Monero:
* Status: `systemctl status monero`
* Logs: `tail -n100 /var/log/monero/monero.log`
* Logs more info: change `log-level=0` to `log-level=1` in `monero.conf` (remember to revert once solved)
## Further improvements
### Periodic restarts
It's likely worthwhile to add peridic auto-restarting to both `tor` and `monerod` every couple hours. Neither daemon is perfect; they can get stuck or leak memory in edge case situations,
like the recent attacks on Tor v3 or DDoS attacks on the Monero network. One possible way would be to use systemd timers.

106
technical-specs.md
View File

@@ -1,106 +0,0 @@
---
title: Monero Technical Specification
has_children: false
---
# Monero Technical Specs
## Live
* Monero blockchain is live since 18 April 2014
## No premine, no instamine, no ICO, no token
* Monero had no premine or instamine
* Monero did not sell any token
* Monero had no presale of any kind
## Proof of Work
* CryptoNight
* 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 (forked on 2019-03-09); "CryptonightR"
* RandomX
* v0 since block height 1978433 (forked on 2019-11-30)
## Difficulty retarget
* every block
* based on the last 720 blocks (24h), excluding 20% of the timestamp outliers
## Block time
* 2 minutes
* may change in the future as long as emission curve is preserved
## Block reward
* smoothly decreasing and subject to penalties for blocks greater than median size of the last 100 blocks (M100)
* 0.6 XMR as of June 2023; 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)
* ~50KB as of June 2020; check [the latest block size](https://bitinfocharts.com/comparison/monero-size.html#3m)
## Current blockchain size
* Pruned node: ~ 57GB as of Jan 2023
* Complete chain without any pruning: ~138GB as of Jan 2023
## Emission curve
### Main emission
* first, the main emission is about to produce ~18.132 million coins by the end of May 2022
* as of June 2023 the emission is about 3 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
* the tail emission kicked in after main emission is done
* it will produce 0.6 XMR per 2-minute block
* this translates to <1% inflation decreasing over time
## Max supply
* ~18.293 million XMR + 0.6 XMR per 2 minutes
* technically infinite but practically deflationary if accounted for lost coins
## Divisibility
* Monero is divisible up to 12 digits
* The smallest unit is called piconero and equals 1e-12 XMR, or 0.000000000001 XMR
## Sender privacy
* ring signatures
* the ring size is 16 (15 decoys)
* assurance: probabilistic / plausible deniability
## Recipient privacy
* stealth addresses
* assurance: strong
## Amount privacy
* ring confidential transactions
* assurance: strong
## IP address privacy
For the full node (`monerod`):
* dandelion++
* assurance: won't protect against ISP/VPN provider, won't protect against the very first remote node in Dandellion++ protocol
* for the full protection user must manually wrap `monerod` with Tor
For the wallet (`monero-wallet-gui` or `monero-wallet-cli`):
* typically wallet runs on the same machine as full node so there is no risk
* if wallet connects to remote full node, there is no IP protection by default
* user must manually wrap wallet with Tor or I2P