gaspersic/go-ethereum
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[DOCS] massive documentation update (#20229)

Browse Source 
This PR:

- reorganizes all documentation pages so they live in the right category
- removes lots of legacy docs
- contains many improvements to active documentation pages

Geth user documentation is now spread across five major categories:

- Install and Build: installation and compile instructions
- Using Geth: this is for pages about general geth usage.
- For dApp Developers: this is for programming guides and functionality specific
   to dapp development. All the dev guides for mobile framework and Go APIs live here.
- JSON-RPC APIs: this has its own section because there is now a sub-page for
   every name space. I have also added an overview text that explains how to set
   up the API servers.
- For Geth Developers: this is for geth contributors
This commit is contained in:
Felix Lange
2019-11-05 13:46:00 +01:00
committed by GitHub
parent 86b20d897e
commit 7416b05b81
76 changed files with 3537 additions and 4680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
docs/_interface/Command-Line-Options.md
View File

@ -1,169 +1,214 @@
---
title: Commandline options
title: Command-line Options
sort_key: A
---
```
$ geth help
$ geth --help
NAME:
geth - the go-ethereum command line interface
Copyright 2013-2018 The go-ethereum Authors
Copyright 2013-2019 The go-ethereum Authors
USAGE:
geth [options] command [command options] [arguments...]
VERSION:
1.8.11-stable
1.9.6-stable
COMMANDS:
account Manage accounts
attach Start an interactive JavaScript environment (connect to node)
bug opens a window to report a bug on the geth repo
console Start an interactive JavaScript environment
copydb Create a local chain from a target chaindata folder
dump Dump a specific block from storage
dumpconfig Show configuration values
export Export blockchain into file
export-preimages Export the preimage database into an RLP stream
import Import a blockchain file
import-preimages Import the preimage database from an RLP stream
init Bootstrap and initialize a new genesis block
js Execute the specified JavaScript files
license Display license information
makecache Generate ethash verification cache (for testing)
makedag Generate ethash mining DAG (for testing)
monitor Monitor and visualize node metrics
removedb Remove blockchain and state databases
version Print version numbers
wallet Manage Ethereum presale wallets
help, h Shows a list of commands or help for one command
account Manage accounts
attach Start an interactive JavaScript environment (connect to node)
console Start an interactive JavaScript environment
copydb Create a local chain from a target chaindata folder
dump Dump a specific block from storage
dumpconfig Show configuration values
export Export blockchain into file
export-preimages Export the preimage database into an RLP stream
import Import a blockchain file
import-preimages Import the preimage database from an RLP stream
init Bootstrap and initialize a new genesis block
inspect Inspect the storage size for each type of data in the database
js Execute the specified JavaScript files
license Display license information
makecache Generate ethash verification cache (for testing)
makedag Generate ethash mining DAG (for testing)
removedb Remove blockchain and state databases
retesteth Launches geth in retesteth mode
version Print version numbers
wallet Manage Ethereum presale wallets
help, h Shows a list of commands or help for one command
ETHEREUM OPTIONS:
--config value TOML configuration file
--datadir "/home/ligi/.ethereum" Data directory for the databases and keystore
--keystore Directory for the keystore (default = inside the datadir)
--nousb Disables monitoring for and managing USB hardware wallets
--networkid value Network identifier (integer, 1=Frontier, 2=Morden (disused), 3=Ropsten, 4=Rinkeby) (default: 1)
--testnet Ropsten network: pre-configured proof-of-work test network
--rinkeby Rinkeby network: pre-configured proof-of-authority test network
--syncmode "fast" Blockchain sync mode ("fast", "full", or "light")
--gcmode value Blockchain garbage collection mode ("full", "archive") (default: "full")
--ethstats value Reporting URL of a ethstats service (nodename:secret@host:port)
--identity value Custom node name
--lightserv value Maximum percentage of time allowed for serving LES requests (0-90) (default: 0)
--lightpeers value Maximum number of LES client peers (default: 100)
--lightkdf Reduce key-derivation RAM & CPU usage at some expense of KDF strength
--config value TOML configuration file
--datadir value Data directory for the databases and keystore (default: "~/Library/Ethereum")
--datadir.ancient value Data directory for ancient chain segments (default = inside chaindata)
--keystore value Directory for the keystore (default = inside the datadir)
--nousb Disables monitoring for and managing USB hardware wallets
--pcscdpath value Path to the smartcard daemon (pcscd) socket file
--networkid value Network identifier (integer, 1=Frontier, 2=Morden (disused), 3=Ropsten, 4=Rinkeby) (default: 1)
--testnet Ropsten network: pre-configured proof-of-work test network
--rinkeby Rinkeby network: pre-configured proof-of-authority test network
--goerli Görli network: pre-configured proof-of-authority test network
--syncmode value Blockchain sync mode ("fast", "full", or "light") (default: fast)
--exitwhensynced Exits after block synchronisation completes
--gcmode value Blockchain garbage collection mode ("full", "archive") (default: "full")
--ethstats value Reporting URL of a ethstats service (nodename:secret@host:port)
--identity value Custom node name
--lightkdf Reduce key-derivation RAM & CPU usage at some expense of KDF strength
--whitelist value Comma separated block number-to-hash mappings to enforce (<number>=<hash>)
LIGHT CLIENT OPTIONS:
--light.serve value Maximum percentage of time allowed for serving LES requests (multi-threaded processing allows values over 100) (default: 0)
--light.ingress value Incoming bandwidth limit for serving light clients (kilobytes/sec, 0 = unlimited) (default: 0)
--light.egress value Outgoing bandwidth limit for serving light clients (kilobytes/sec, 0 = unlimited) (default: 0)
--light.maxpeers value Maximum number of light clients to serve, or light servers to attach to (default: 100)
--ulc.servers value List of trusted ultra-light servers
--ulc.fraction value Minimum % of trusted ultra-light servers required to announce a new head (default: 75)
--ulc.onlyannounce Ultra light server sends announcements only
DEVELOPER CHAIN OPTIONS:
--dev Ephemeral proof-of-authority network with a pre-funded developer account, mining enabled
--dev.period value Block period to use in developer mode (0 = mine only if transaction pending) (default: 0)
--dev Ephemeral proof-of-authority network with a pre-funded developer account, mining enabled
--dev.period value Block period to use in developer mode (0 = mine only if transaction pending) (default: 0)
ETHASH OPTIONS:
--ethash.cachedir Directory to store the ethash verification caches (default = inside the datadir)
--ethash.cachesinmem value Number of recent ethash caches to keep in memory (16MB each) (default: 2)
--ethash.cachesondisk value Number of recent ethash caches to keep on disk (16MB each) (default: 3)
--ethash.dagdir "/home/ligi/.ethash" Directory to store the ethash mining DAGs (default = inside home folder)
--ethash.dagsinmem value Number of recent ethash mining DAGs to keep in memory (1+GB each) (default: 1)
--ethash.dagsondisk value Number of recent ethash mining DAGs to keep on disk (1+GB each) (default: 2)
--ethash.cachedir value Directory to store the ethash verification caches (default = inside the datadir)
--ethash.cachesinmem value Number of recent ethash caches to keep in memory (16MB each) (default: 2)
--ethash.cachesondisk value Number of recent ethash caches to keep on disk (16MB each) (default: 3)
--ethash.dagdir value Directory to store the ethash mining DAGs (default: "~/Library/Ethash")
--ethash.dagsinmem value Number of recent ethash mining DAGs to keep in memory (1+GB each) (default: 1)
--ethash.dagsondisk value Number of recent ethash mining DAGs to keep on disk (1+GB each) (default: 2)
TRANSACTION POOL OPTIONS:
--txpool.nolocals Disables price exemptions for locally submitted transactions
--txpool.journal value Disk journal for local transaction to survive node restarts (default: "transactions.rlp")
--txpool.rejournal value Time interval to regenerate the local transaction journal (default: 1h0m0s)
--txpool.pricelimit value Minimum gas price limit to enforce for acceptance into the pool (default: 1)
--txpool.pricebump value Price bump percentage to replace an already existing transaction (default: 10)
--txpool.accountslots value Minimum number of executable transaction slots guaranteed per account (default: 16)
--txpool.globalslots value Maximum number of executable transaction slots for all accounts (default: 4096)
--txpool.accountqueue value Maximum number of non-executable transaction slots permitted per account (default: 64)
--txpool.globalqueue value Maximum number of non-executable transaction slots for all accounts (default: 1024)
--txpool.lifetime value Maximum amount of time non-executable transaction are queued (default: 3h0m0s)
--txpool.locals value Comma separated accounts to treat as locals (no flush, priority inclusion)
--txpool.nolocals Disables price exemptions for locally submitted transactions
--txpool.journal value Disk journal for local transaction to survive node restarts (default: "transactions.rlp")
--txpool.rejournal value Time interval to regenerate the local transaction journal (default: 1h0m0s)
--txpool.pricelimit value Minimum gas price limit to enforce for acceptance into the pool (default: 1)
--txpool.pricebump value Price bump percentage to replace an already existing transaction (default: 10)
--txpool.accountslots value Minimum number of executable transaction slots guaranteed per account (default: 16)
--txpool.globalslots value Maximum number of executable transaction slots for all accounts (default: 4096)
--txpool.accountqueue value Maximum number of non-executable transaction slots permitted per account (default: 64)
--txpool.globalqueue value Maximum number of non-executable transaction slots for all accounts (default: 1024)
--txpool.lifetime value Maximum amount of time non-executable transaction are queued (default: 3h0m0s)
PERFORMANCE TUNING OPTIONS:
--cache value Megabytes of memory allocated to internal caching (default: 1024)
--cache.database value Percentage of cache memory allowance to use for database io (default: 75)
--cache.gc value Percentage of cache memory allowance to use for trie pruning (default: 25)
--trie-cache-gens value Number of trie node generations to keep in memory (default: 120)
--cache value Megabytes of memory allocated to internal caching (default = 4096 mainnet full node, 128 light mode) (default: 1024)
--cache.database value Percentage of cache memory allowance to use for database io (default: 50)
--cache.trie value Percentage of cache memory allowance to use for trie caching (default = 25% full mode, 50% archive mode) (default: 25)
--cache.gc value Percentage of cache memory allowance to use for trie pruning (default = 25% full mode, 0% archive mode) (default: 25)
--cache.noprefetch Disable heuristic state prefetch during block import (less CPU and disk IO, more time waiting for data)
ACCOUNT OPTIONS:
--unlock value Comma separated list of accounts to unlock
--password value Password file to use for non-interactive password input
--unlock value Comma separated list of accounts to unlock
--password value Password file to use for non-interactive password input
--signer value External signer (url or path to ipc file)
--allow-insecure-unlock Allow insecure account unlocking when account-related RPCs are exposed by http
API AND CONSOLE OPTIONS:
--rpc Enable the HTTP-RPC server
--rpcaddr value HTTP-RPC server listening interface (default: "localhost")
--rpcport value HTTP-RPC server listening port (default: 8545)
--rpcapi value API's offered over the HTTP-RPC interface
--ws Enable the WS-RPC server
--wsaddr value WS-RPC server listening interface (default: "localhost")
--wsport value WS-RPC server listening port (default: 8546)
--wsapi value API's offered over the WS-RPC interface
--wsorigins value Origins from which to accept websockets requests
--ipcdisable Disable the IPC-RPC server
--ipcpath Filename for IPC socket/pipe within the datadir (explicit paths escape it)
--rpccorsdomain value Comma separated list of domains from which to accept cross origin requests (browser enforced)
--rpcvhosts value Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
--jspath loadScript JavaScript root path for loadScript (default: ".")
--exec value Execute JavaScript statement
--preload value Comma separated list of JavaScript files to preload into the console
--ipcdisable Disable the IPC-RPC server
--ipcpath value Filename for IPC socket/pipe within the datadir (explicit paths escape it)
--rpc Enable the HTTP-RPC server
--rpcaddr value HTTP-RPC server listening interface (default: "localhost")
--rpcport value HTTP-RPC server listening port (default: 8545)
--rpcapi value API's offered over the HTTP-RPC interface
--rpc.gascap value Sets a cap on gas that can be used in eth_call/estimateGas (default: 0)
--rpccorsdomain value Comma separated list of domains from which to accept cross origin requests (browser enforced)
--rpcvhosts value Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
--ws Enable the WS-RPC server
--wsaddr value WS-RPC server listening interface (default: "localhost")
--wsport value WS-RPC server listening port (default: 8546)
--wsapi value API's offered over the WS-RPC interface
--wsorigins value Origins from which to accept websockets requests
--graphql Enable the GraphQL server
--graphql.addr value GraphQL server listening interface (default: "localhost")
--graphql.port value GraphQL server listening port (default: 8547)
--graphql.corsdomain value Comma separated list of domains from which to accept cross origin requests (browser enforced)
--graphql.vhosts value Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default: "localhost")
--jspath loadScript JavaScript root path for loadScript (default: ".")
--exec value Execute JavaScript statement
--preload value Comma separated list of JavaScript files to preload into the console
NETWORKING OPTIONS:
--bootnodes value Comma separated enode URLs for P2P discovery bootstrap (set v4+v5 instead for light servers)
--bootnodesv4 value Comma separated enode URLs for P2P v4 discovery bootstrap (light server, full nodes)
--bootnodesv5 value Comma separated enode URLs for P2P v5 discovery bootstrap (light server, light nodes)
--port value Network listening port (default: 30303)
--maxpeers value Maximum number of network peers (network disabled if set to 0) (default: 25)
--maxpendpeers value Maximum number of pending connection attempts (defaults used if set to 0) (default: 0)
--nat value NAT port mapping mechanism (any|none|upnp|pmp|extip:<IP>) (default: "any")
--nodiscover Disables the peer discovery mechanism (manual peer addition)
--v5disc Enables the experimental RLPx V5 (Topic Discovery) mechanism
--netrestrict value Restricts network communication to the given IP networks (CIDR masks)
--nodekey value P2P node key file
--nodekeyhex value P2P node key as hex (for testing)
--bootnodes value Comma separated enode URLs for P2P discovery bootstrap (set v4+v5 instead for light servers)
--bootnodesv4 value Comma separated enode URLs for P2P v4 discovery bootstrap (light server, full nodes)
--bootnodesv5 value Comma separated enode URLs for P2P v5 discovery bootstrap (light server, light nodes)
--port value Network listening port (default: 30303)
--maxpeers value Maximum number of network peers (network disabled if set to 0) (default: 50)
--maxpendpeers value Maximum number of pending connection attempts (defaults used if set to 0) (default: 0)
--nat value NAT port mapping mechanism (any|none|upnp|pmp|extip:<IP>) (default: "any")
--nodiscover Disables the peer discovery mechanism (manual peer addition)
--v5disc Enables the experimental RLPx V5 (Topic Discovery) mechanism
--netrestrict value Restricts network communication to the given IP networks (CIDR masks)
--nodekey value P2P node key file
--nodekeyhex value P2P node key as hex (for testing)
MINER OPTIONS:
--mine Enable mining
--minerthreads value Number of CPU threads to use for mining (default: 8)
--etherbase value Public address for block mining rewards (default = first account created) (default: "0")
--targetgaslimit value Target gas limit sets the artificial target gas floor for the blocks to mine (default: 4712388)
--gasprice "18000000000" Minimal gas price to accept for mining a transactions
--extradata value Block extra data set by the miner (default = client version)
--mine Enable mining
--miner.threads value Number of CPU threads to use for mining (default: 0)
--miner.notify value Comma separated HTTP URL list to notify of new work packages
--miner.gasprice value Minimum gas price for mining a transaction (default: 1000000000)
--miner.gastarget value Target gas floor for mined blocks (default: 8000000)
--miner.gaslimit value Target gas ceiling for mined blocks (default: 8000000)
--miner.etherbase value Public address for block mining rewards (default = first account) (default: "0")
--miner.extradata value Block extra data set by the miner (default = client version)
--miner.recommit value Time interval to recreate the block being mined (default: 3s)
--miner.noverify Disable remote sealing verification
GAS PRICE ORACLE OPTIONS:
--gpoblocks value Number of recent blocks to check for gas prices (default: 20)
--gpopercentile value Suggested gas price is the given percentile of a set of recent transaction gas prices (default: 60)
--gpoblocks value Number of recent blocks to check for gas prices (default: 20)
--gpopercentile value Suggested gas price is the given percentile of a set of recent transaction gas prices (default: 60)
VIRTUAL MACHINE OPTIONS:
--vmdebug Record information useful for VM and contract debugging
--vmdebug Record information useful for VM and contract debugging
--vm.evm value External EVM configuration (default = built-in interpreter)
--vm.ewasm value External ewasm configuration (default = built-in interpreter)
LOGGING AND DEBUGGING OPTIONS:
--metrics Enable metrics collection and reporting
--fakepow Disables proof-of-work verification
--nocompaction Disables db compaction after import
--verbosity value Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (default: 3)
--vmodule value Per-module verbosity: comma-separated list of <pattern>=<level> (e.g. eth/*=5,p2p=4)
--backtrace value Request a stack trace at a specific logging statement (e.g. "block.go:271")
--debug Prepends log messages with call-site location (file and line number)
--pprof Enable the pprof HTTP server
--pprofaddr value pprof HTTP server listening interface (default: "127.0.0.1")
--pprofport value pprof HTTP server listening port (default: 6060)
--memprofilerate value Turn on memory profiling with the given rate (default: 524288)
--blockprofilerate value Turn on block profiling with the given rate (default: 0)
--cpuprofile value Write CPU profile to the given file
--trace value Write execution trace to the given file
--fakepow Disables proof-of-work verification
--nocompaction Disables db compaction after import
--verbosity value Logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (default: 3)
--vmodule value Per-module verbosity: comma-separated list of <pattern>=<level> (e.g. eth/*=5,p2p=4)
--backtrace value Request a stack trace at a specific logging statement (e.g. "block.go:271")
--debug Prepends log messages with call-site location (file and line number)
--pprof Enable the pprof HTTP server
--pprofaddr value pprof HTTP server listening interface (default: "127.0.0.1")
--pprofport value pprof HTTP server listening port (default: 6060)
--memprofilerate value Turn on memory profiling with the given rate (default: 524288)
--blockprofilerate value Turn on block profiling with the given rate (default: 0)
--cpuprofile value Write CPU profile to the given file
--trace value Write execution trace to the given file
METRICS AND STATS OPTIONS:
--metrics Enable metrics collection and reporting
--metrics.expensive Enable expensive metrics collection and reporting
--metrics.influxdb Enable metrics export/push to an external InfluxDB database
--metrics.influxdb.endpoint value InfluxDB API endpoint to report metrics to (default: "http://localhost:8086")
--metrics.influxdb.database value InfluxDB database name to push reported metrics to (default: "geth")
--metrics.influxdb.username value Username to authorize access to the database (default: "test")
--metrics.influxdb.password value Password to authorize access to the database (default: "test")
--metrics.influxdb.tags value Comma-separated InfluxDB tags (key/values) attached to all measurements (default: "host=localhost")
WHISPER (EXPERIMENTAL) OPTIONS:
--shh Enable Whisper
--shh.maxmessagesize value Max message size accepted (default: 1048576)
--shh.pow value Minimum POW accepted (default: 0.2)
--shh Enable Whisper
--shh.maxmessagesize value Max message size accepted (default: 1048576)
--shh.pow value Minimum POW accepted (default: 0.2)
--shh.restrict-light Restrict connection between two whisper light clients
DEPRECATED OPTIONS:
--fast Enable fast syncing through state downloads (replaced by --syncmode)
--light Enable light client mode (replaced by --syncmode)
--lightserv value Maximum percentage of time allowed for serving LES requests (deprecated, use --light.serve) (default: 0)
--lightpeers value Maximum number of light clients to serve, or light servers to attach to (deprecated, use --light.maxpeers) (default: 100)
--minerthreads value Number of CPU threads to use for mining (deprecated, use --miner.threads) (default: 0)
--targetgaslimit value Target gas floor for mined blocks (deprecated, use --miner.gastarget) (default: 8000000)
--gasprice value Minimum gas price for mining a transaction (deprecated, use --miner.gasprice) (default: 1000000000)
--etherbase value Public address for block mining rewards (default = first account, deprecated, use --miner.etherbase) (default: "0")
--extradata value Block extra data set by the miner (default = client version, deprecated, use --miner.extradata)
MISC OPTIONS:
--help, -h show help
--override.istanbul value Manually specify Istanbul fork-block, overriding the bundled setting (default: 0)
--help, -h show help
COPYRIGHT:
Copyright 2013-2018 The go-ethereum Authors
```
Copyright 2013-2019 The go-ethereum Authors
```

61
docs/_interface/FAQ.md Normal file
View File

@ -0,0 +1,61 @@
---
title: FAQ
permalink: docs/faq
sort_key: C
---
**Q.** I noticed my peercount slowly decrease, and now it is at 0. Restarting doesn't get any peers.
**A.** Check and sync your clock with ntp. [Example](http://askubuntu.com/questions/254826/how-to-force-a-clock-update-using-ntp) `sudo ntpdate -s time.nist.gov`
---
**Q.** I would like to run multiple geth instances but got the error "Fatal: blockchain db err: resource temporarily unavailable".
**A.** Geth uses a datadir to store the blockchain, accounts and some additional information. This directory cannot be shared between running instances. If you would like to run multiple instances follow [these](../doc/setting-up-private-network-or-local-cluster) instructions.
---
**Q.** How do Ethereum syncing work?
**A.** The current default mode of sync for Geth is called fast sync. Instead of starting from the genesis block and reprocessing all the transactions that ever occurred (which could take weeks), fast sync downloads the blocks, and only verifies the associated proof-of-works. Downloading all the blocks is a straightforward and fast procedure and will relatively quickly reassemble the entire chain.
Many people falsely assume that because they have the blocks, they are in sync. Unfortunately this is not the case, since no transaction was executed, so we do not have any account state available (ie. balances, nonces, smart contract code and data). These need to be downloaded separately and cross checked with the latest blocks. This phase is called the state trie download and it actually runs concurrently with the block downloads; alas it take a lot longer nowadays than downloading the blocks.
So, what's the state trie? In the Ethereum mainnet, there are a ton of accounts already, which track the balance, nonce, etc of each user/contract. The accounts themselves are however insufficient to run a node, they need to be cryptographically linked to each block so that nodes can actually verify that the account's are not tampered with. This cryptographic linking is done by creating a tree data structure above the accounts, each level aggregating the layer below it into an ever smaller layer, until you reach the single root. This gigantic data structure containing all the accounts and the intermediate cryptographic proofs is called the state trie.
Ok, so why does this pose a problem? This trie data structure is an intricate interlink of hundreds of millions of tiny cryptographic proofs (trie nodes). To truly have a synchronized node, you need to download all the account data, as well as all the tiny cryptographic proofs to verify that noone in the network is trying to cheat you. This itself is already a crazy number of data items. The part where it gets even messier is that this data is constantly morphing: at every block (15s), about 1000 nodes are deleted from this trie and about 2000 new ones are added. This means your node needs to synchronize a dataset that is changing 200 times per second. The worst part is that while you are synchronizing, the network is moving forward, and state that you begun to download might disappear while you're downloading, so your node needs to constantly follow the network while trying to gather all the recent data. But until you actually do gather all the data, your local node is not usable since it cannot cryptographically prove anything about any accounts.
If you see that you are 64 blocks behind mainnet, you aren't yet synchronized, not even close. You are just done with the block download phase and still running the state downloads. You can see this yourself via the seemingly endless `Imported state entries [...]` stream of logs. You'll need to wait that out too before your node comes truly online.
---
**Q: The node just hangs on importing state enties?!**
**A**: The node doesn't hang, it just doesn't know how large the state trie is in advance so it keeps on going and going and going until it discovers and downloads the entire thing.
The reason is that a block in Ethereum only contains the state root, a single hash of the root node. When the node begins synchronizing, it knows about exactly 1 node and tries to download it. That node, can refer up to 16 new nodes, so in the next step, we'll know about 16 new nodes and try to download those. As we go along the download, most of the nodes will reference new ones that we didn't know about until then. This is why you might be tempted to think it's stuck on the same numbers. It is not, rather it's discovering and downloading the trie as it goes along.
---
**Q: I'm stuck at 64 blocks behind mainnet?!**
*A:* As explained above, you are not stuck, just finished with the block download phase, waiting for the state download phase to complete too. This latter phase nowadays take a lot longer than just getting the blocks.
---
**Q: Why does downloading the state take so long, I have good bandwidth?**
**A:** State sync is mostly limited by disk IO, not bandwidth.
The state trie in Ethereum contains hundreds of millions of nodes, most of which take the form of a single hash referencing up to 16 other hashes. This is a horrible way to store data on a disk, because there's almost no structure in it, just random numbers referencing even more random numbers. This makes any underlying database weep, as it cannot optimize storing and looking up the data in any meaningful way.
Not only is storing the data very suboptimal, but due to the 200 modification / second and pruning of past data, we cannot even download it is a properly pre-processed way to make it import faster without the underlying database shuffling it around too much. The end result is that even a fast sync nowadays incurs a huge disk IO cost, which is too much for a mechanical hard drive.
---
**Q: Wait, so I can't run a full node on an HDD?**
**A:** Unfortunately not. Doing a fast sync on an HDD will take more time than you're willing to wait with the current data schema. Even if you do wait it out, an HDD will not be able to keep up with the read/write requirements of transaction processing on mainnet.
You however should be able to run a light client on an HDD with minimal impact on system resources. If you wish to run a full node however, an SSD is your only option.

95
docs/_interface/JavaScript-Console.md
View File

@ -1,77 +1,84 @@
---
title: JavaScript console
title: JavaScript Console
sort_key: B
---
Ethereum implements a **javascript runtime environment** (JSRE) that can be used in either interactive (console) or non-interactive (script) mode.
Ethereum's Javascript console exposes the full [web3 JavaScript Dapp API](https://github.com/ethereum/wiki/wiki/JavaScript-API) and the admin API.
## Interactive use: the JSRE REPL Console
The Geth JavaScript console exposes the full [web3 JavaScript Dapp
API](https://github.com/ethereum/wiki/wiki/JavaScript-API) and further administrative
APIs.
The `ethereum CLI` executable `geth` has a JavaScript console (a **Read, Evaluate & Print Loop** = REPL exposing the JSRE), which can be started with the `console` or `attach` subcommand. The `console` subcommands starts the geth node and then opens the console. The `attach` subcommand will not start the geth node but instead tries to open the console on a running geth instance.
## Interactive Use: The Console
$ geth console
$ geth attach
The geth JavaScript console is started with the `console` or `attach` geth sub-commands.
The `console` subcommands starts the geth node and then opens the console. The `attach`
subcommand attaches to the console to an already-running geth instance.
The attach node accepts an endpoint in case the geth node is running with a non default ipc endpoint or you would like to connect over the rpc interface.
geth console
geth attach
$ geth attach /some/custom/path.ipc
$ geth attach http://191.168.1.1:8545
$ geth attach ws://191.168.1.1:8546
Attach mode accepts an endpoint in case the geth node is running with a non default
ipc endpoint or you would like to connect over the rpc interface.
Note that by default the geth node doesn't start the http and weboscket service and not all functionality is provided over these interfaces due to security reasons. These defaults can be overridden when the `--rpcapi` and `--wsapi` arguments when the geth node is started, or with [admin.startRPC](management-apis#admin_startrpc) and [admin.startWS](management-apis#admin_startws).
geth attach /some/custom/path.ipc
eth attach http://191.168.1.1:8545
geth attach ws://191.168.1.1:8546
Note that by default the geth node doesn't start the HTTP and WebSocket servers and not
all functionality is provided over these interfaces for security reasons. These defaults
can be overridden when the `--rpcapi` and `--wsapi` arguments when the geth node is
started, or with [admin.startRPC](../rpc/ns-admin#admin_startrpc) and
[admin.startWS](../rpc/ns-admin#admin_startws).
If you need log information, start with:
$ geth --verbosity 5 console 2>> /tmp/eth.log
geth console --verbosity 5 2>> /tmp/eth.log
Otherwise mute your logs, so that it does not pollute your console:
$ geth console 2> /dev/null
geth console 2> /dev/null
or
Geth has support to load custom JavaScript files into the console through the `--preload`
option. This can be used to load often used functions, or to setup web3 contract objects.
$ geth --verbosity 0 console
geth console --preload "/my/scripts/folder/utils.js,/my/scripts/folder/contracts.js"
Geth has support to load custom JavaScript files into the console through the `--preload` argument. This can be used to load often used functions, setup web3 contract objects, or ...
```
geth --preload "/my/scripts/folder/utils.js,/my/scripts/folder/contracts.js" console
```
## Non-interactive Use: Script Mode
It's also possible to execute files to the JavaScript interpreter. The `console` and
`attach` subcommand accept the `--exec` argument which is a javascript statement.
## Non-interactive use: JSRE script mode
It's also possible to execute files to the JavaScript interpreter. The `console` and `attach` subcommand accept the `--exec` argument which is a javascript statement.
$ geth --exec "eth.blockNumber" attach
geth attach --exec "eth.blockNumber"
This prints the current block number of a running geth instance.
Or execute a local script with more complex statements on a remote node over http:
$ geth --exec 'loadScript("/tmp/checkbalances.js")' attach http://123.123.123.123:8545
$ geth --jspath "/tmp" --exec 'loadScript("checkbalances.js")' attach http://123.123.123.123:8545
geth attach http://geth.example.org:8545 --exec 'loadScript("/tmp/checkbalances.js")'
geth attach http://geth.example.org:8545 --jspath "/tmp" --exec 'loadScript("checkbalances.js")'
Use the `--jspath <path/to/my/js/root>` to set a libdir for your js scripts. Parameters to `loadScript()` with no absolute path will be understood relative to this directory.
Use the `--jspath <path/to/my/js/root>` to set a library directory for your js scripts.
Parameters to `loadScript()` with no absolute path will be understood relative to this
directory.
You can exit the console cleanly by typing `exit` or simply with `CTRL-C`.
You can exit the console by typing `exit` or simply with `CTRL-C`.
## Caveat
## Caveats
The go-ethereum JSRE uses the [Otto JS VM](https://github.com/robertkrimen/otto) which has some limitations:
go-ethereum uses the [Otto JS VM](https://github.com/robertkrimen/otto) which has some
limitations:
* `"use strict"` will parse, but does nothing.
* The regular expression engine (re2/regexp) is not fully compatible with the ECMA5 specification.
* The regular expression engine (re2/regexp) is not fully compatible with the ECMA5
specification.
Note that the other known limitation of Otto (namely the lack of timers) is taken care of. Ethereum JSRE implements both `setTimeout` and `setInterval`. In addition to this, the console provides `admin.sleep(seconds)` as well as a "blocktime sleep" method `admin.sleepBlocks(number)`.
`web3.js` uses the [`bignumber.js`](https://github.com/MikeMcl/bignumber.js) library.
This library is auto-loaded into the console.
Since `web3.js` uses the [`bignumber.js`](https://github.com/MikeMcl/bignumber.js) library (MIT Expat Licence), it is also autoloded.
### Timers
## Timers
In addition to the full functionality of JS (as per ECMA5), the ethereum JSRE is augmented with various timers. It implements `setInterval`, `clearInterval`, `setTimeout`, `clearTimeout` you may be used to using in browser windows. It also provides implementation for `admin.sleep(seconds)` and a block based timer, `admin.sleepBlocks(n)` which sleeps till the number of new blocks added is equal to or greater than `n`, think "wait for n confirmations".
# Management APIs
Beside the official [DApp API](https://github.com/ethereum/wiki/wiki/JSON-RPC) interface the go ethereum node has support for additional management API's. These API's are offered using [JSON-RPC](http://www.jsonrpc.org/specification) and follow the same conventions as used in the DApp API. The go ethereum package comes with a console client which has support for all additional API's.
[The management API has its own page](management-apis).
In addition to the full functionality of JS (as per ECMA5), the ethereum JSRE is augmented
with various timers. It implements `setInterval`, `clearInterval`, `setTimeout`,
`clearTimeout` you may be used to using in browser windows. It also provides
implementation for `admin.sleep(seconds)` and a block based timer, `admin.sleepBlocks(n)`
which sleeps till the number of new blocks added is equal to or greater than `n`, think
"wait for n confirmations".

1399
docs/_interface/Management-APIs.md
View File

File diff suppressed because it is too large Load Diff

4
docs/_interface/Managing-your-accounts.md
View File

@ -1,6 +1,8 @@
---
title: Managing your accounts
title: Managing Your Accounts
sort_key: B
---
**WARNING**
Remember your password.

160
docs/_interface/mining.md Normal file
View File

@ -0,0 +1,160 @@
---
title: Mining
sort_key: B
---
This document explains how to set up geth for mining. The Ethereum wiki also has a [page
about mining](eth-wiki-mining), be sure to check that one as well.
Mining is the process through which new blocks are created. Geth actually creates new
blocks all the time, but these blocks need to be secured through proof-of-work so they
will be accepted by other nodes. Mining is all about creating these proof-of-work values.
The proof-of-work computation can be performed in multiple ways. Geth includes a CPU
miner, which does mining within the geth process. We discourage using the CPU miner with
the Ethereum mainnet. If you want to mine real ether, use GPU mining. Your best option for
doing that is the [ethminer](ethminer) software.
Always ensure your blockchain is fully synchronised with the chain before starting to
mine, otherwise you will not be mining on the correct chain and your block rewards will
not be valueable.
## GPU mining
The ethash algorithm is memory hard and in order to fit the DAG into memory, it needs
1-2GB of RAM on each GPU. If you get `Error GPU mining. GPU memory fragmentation?` you
don't have enough memory.
### Installing ethminer
To get ethminer, you need to install the ethminer binary package or build it from source.
See <https://github.com/ethereum-mining/ethminer/#build> for the official ethminer
build/install instructions. At the time of writing, ethminer only provides a binary for
Microsoft Windows.
### Using ethminer with geth
First create an account to hold your block rewards.
geth account new
Follow the prompts and enter a good password. **DO NOT FORGET YOUR PASSWORD**. Also take
note of the public Ethereum address which is printed at the end of the account creation
process. In the following examples, we will use 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10
as the example address.
Now start geth and wait for it to sync the blockchain. This will take quite a while.
geth --rpc --etherbase 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10
Now we're ready to start mining. In a new terminal session, run ethminer and connect it to geth:
ethminer -G -P http://127.0.0.1:8545
`ethminer` communicates with geth on port 8545 (the default RPC port in geth). You can
change this by giving the [`--rpcport` option](../rpc/index) to `geth`. Ethminer will find
get on any port. You also need to set the port on `ethminer` with `-P
http://127.0.0.1:3301`. Setting up custom ports is necessary if you want several instances
mining on the same computer. If you are testing on a private cluster, we recommend you use
CPU mining instead.
If the default for `ethminer` does not work try to specify the OpenCL device with:
`--opencl-device X` where X is 0, 1, 2, etc. When running `ethminer` with `-M`
(benchmark), you should see something like:
Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" }
Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " }
**Note** hashrate info is not available in `geth` when GPU mining. Check your hashrate
with `ethminer`, `miner.hashrate` will always report 0.
## CPU Mining with Geth
When you start up your ethereum node with `geth` it is not mining by default. To start it
in mining mode, you use the `--mine` command-line flag. The `--minerthreads` parameter can
be used to set the number parallel mining threads (defaulting to the total number of
processor cores).
geth --mine --minerthreads=4
You can also start and stop CPU mining at runtime using the
[console](../interface/javascript-console). `miner.start` takes an optional parameter for
the number of miner threads.
> miner.start(8)
true
> miner.stop()
true
Note that mining for real ether only makes sense if you are in sync with the network
(since you mine on top of the consensus block). Therefore the eth blockchain
downloader/synchroniser will delay mining until syncing is complete, and after that mining
automatically starts unless you cancel your intention with `miner.stop()`.
In order to earn ether you must have your **etherbase** (or **coinbase**) address set.
This etherbase defaults to your [primary account](../interface/managing-your-accounts). If
you don't have an etherbase address, then `geth --mine` will not start up.
You can set your etherbase on the command line:
geth --etherbase '0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10' --mine 2>> geth.log
You can reset your etherbase on the console too:
> miner.setEtherbase(eth.accounts[2])
Note that your etherbase does not need to be an address of a local account, just an
existing one.
There is an option [to add extra data](../interface/javascript-console) (32 bytes only) to
your mined blocks. By convention this is interpreted as a unicode string, so you can set
your short vanity tag.
> miner.setExtra("ΞTHΞЯSPHΞЯΞ")
You can check your hashrate with [miner.hashrate](../interface/javascript-console), the
result is in H/s (Hash operations per second).
> miner.hashrate
712000
After you successfully mined some blocks, you can check the ether balance of your
etherbase account. Now assuming your etherbase is a local account:
> eth.getBalance(eth.coinbase).toNumber();
'34698870000000'
You can check which blocks are mined by a particular miner (address) with the following
code snippet on the console:
> function minedBlocks(lastn, addr) {
addrs = [];
if (!addr) {
addr = eth.coinbase
}
limit = eth.blockNumber - lastn
for (i = eth.blockNumber; i >= limit; i--) {
if (eth.getBlock(i).miner == addr) {
addrs.push(i)
}
}
return addrs
}
// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase
// (more precisely blocks the mining reward for which is sent to your coinbase).
> minedBlocks(1000, eth.coinbase)
[352708, 352655, 352559]
Note that it will happen often that you find a block yet it never makes it to the
canonical chain. This means when you locally include your mined block, the current state
will show the mining reward credited to your account, however, after a while, the better
chain is discovered and we switch to a chain in which your block is not included and
therefore no mining reward is credited. Therefore it is quite possible that as a miner
monitoring their coinbase balance will find that it may fluctuate quite a bit.
The logs show locally mined blocks confirmed after 5 blocks. At the moment you may find it
easier and faster to generate the list of your mined blocks from these logs.
[eth-wiki-mining]: https://github.com/ethereum/wiki/wiki/Mining
[ethminer]: https://github.com/ethereum-mining/ethminer

154
docs/_interface/peer-to-peer.md Normal file
View File

@ -0,0 +1,154 @@
---
title: Connecting To The Network
sort_key: B
---
## How Peers Are Found
Geth continuously attempts to connect to other nodes on the network until it has peers. If
you have UPnP enabled on your router or run ethereum on an Internet-facing server, it will
also accept connections from other nodes.
Geth finds peers through something called the discovery protocol. In the discovery
protocol, nodes are gossipping with each other to find out about other nodes on the
network. In order to get going initially, geth uses a set of bootstrap nodes whose
endpoints are recorded in the source code.
To change the bootnodes on startup, use the `--bootnodes` option and separate the nodes by
commas. For example:
geth --bootnodes enode://pubkey1@ip1:port1,enode://pubkey2@ip2:port2,enode://pubkey3@ip3:port3
## Common Problems With Connectivity
Sometimes you just can't get connected. The most common reasons are as follows:
- Your local time might be incorrect. An accurate clock is required to participate in the
Ethereum network. Check your OS for how to resync your clock (example sudo ntpdate -s
time.nist.gov) because even 12 seconds too fast can lead to 0 peers.
- Some firewall configurations can prevent UDP traffic from flowing. You can use the
static nodes feature or `admin.addPeer()` on the console to configure connections by
hand.
To start geth without the discovery protocol, you can use the `--nodiscover` parameter.
You only want this is you are running a test node or an experimental test network with
fixed nodes.
## Checking Connectivity
To check how many peers the client is connected to in the interactive console, the `net`
module has two attributes give you info about the number of peers and whether you are a
listening node.
```js
> net.listening
true
> net.peerCount
4
```
To get more information about the connected peers, such as IP address and port number,
supported protocols, use the `peers()` function of the `admin` object. `admin.peers()`
returns the list of currently connected peers.
```
> admin.peers
[{
ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b',
Name: 'Geth/v0.9.14/linux/go1.4.2',
Caps: 'eth/60',
RemoteAddress: '5.9.150.40:30301',
LocalAddress: '192.168.0.28:39219'
}, {
ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c',
Name: 'Geth/v0.9.15/linux/go1.4.2',
Caps: 'eth/60',
RemoteAddress: '52.16.188.185:30303',
LocalAddress: '192.168.0.28:50995'
}, {
ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172',
Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9',
Caps: 'eth/60, p2p/3',
RemoteAddress: '144.76.62.101:30303',
LocalAddress: '192.168.0.28:40454'
}, {
ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0',
Name: '++eth/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int',
Caps: 'eth/60, shh/2',
RemoteAddress: '129.16.191.64:30303',
LocalAddress: '192.168.0.28:39705'
} ]
```
To check the ports used by geth and also find your enode URI run:
```
> admin.nodeInfo
{
Name: 'Geth/v0.9.14/darwin/go1.4.2',
NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303',
NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694',
IP: '::',
DiscPort: 30303,
TCPPort: 30303,
Td: '2044952618444',
ListenAddr: '[::]:30303'
}
```
## Custom Networks
Sometimes you might not need to connect to the live public network, you can instead choose
to create your own private testnet. This is very useful if you don't need to test external
contracts and want just to test the technology, because you won't have to compete with
other miners and will easily generate a lot of test ether to play around (replace 12345
with any non-negative number):
geth -—networkid="12345" console
It is also possible to run geth with a custom genesis block from a JSON file by supplying
the `--genesis` flag. The genesis JSON file should have the following format:
```js
{
"alloc": {
"dbdbdb2cbd23b783741e8d7fcf51e459b497e4a6": {
"balance": "1606938044258990275541962092341162602522202993782792835301376"
},
"e6716f9544a56c530d868e4bfbacb172315bdead": {
"balance": "1606938044258990275541962092341162602522202993782792835301376"
},
...
},
"nonce": "0x000000000000002a",
"difficulty": "0x020000",
"mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"coinbase": "0x0000000000000000000000000000000000000000",
"timestamp": "0x00",
"parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"extraData": "0x",
"gasLimit": "0x2fefd8"
}
```
## Static nodes
Geth also supports a feature called static nodes if you have certain peers you always want
to connect to. Static nodes are re-connected on disconnects. You can configure permanent
static nodes by putting something like the following into
`<datadir>/geth/static-nodes.json`:
```js
[
"enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303",
"enode://pubkey@ip:port"
]
```
You can also add static nodes at runtime via the js console using
[`admin.addPeer()`](../interface/management-apis#admin_addpeer):
```js
admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
```