github.com/codysnider/go-ethereum@v1.10.18-0.20220420071915-14f4ae99222a/README.md (about) 1 ## Go Ethereum 2 3 Official Golang implementation of the Ethereum protocol. 4 5 [](https://pkg.go.dev/github.com/ethereum/go-ethereum?tab=doc) 8 [](https://goreportcard.com/report/github.com/ethereum/go-ethereum) 9 [](https://travis-ci.com/ethereum/go-ethereum) 10 [](https://discord.gg/nthXNEv) 11 12 Automated builds are available for stable releases and the unstable master branch. Binary 13 archives are published at https://geth.ethereum.org/downloads/. 14 15 ## Building the source 16 17 For prerequisites and detailed build instructions please read the [Installation Instructions](https://geth.ethereum.org/docs/install-and-build/installing-geth). 18 19 Building `geth` requires both a Go (version 1.14 or later) and a C compiler. You can install 20 them using your favourite package manager. Once the dependencies are installed, run 21 22 ```shell 23 make geth 24 ``` 25 26 or, to build the full suite of utilities: 27 28 ```shell 29 make all 30 ``` 31 32 ## Executables 33 34 The go-ethereum project comes with several wrappers/executables found in the `cmd` 35 directory. 36 37 | Command | Description | 38 | :-----------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 39 | **`geth`** | Our main Ethereum CLI client. It is the entry point into the Ethereum network (main-, test- or private net), capable of running as a full node (default), archive node (retaining all historical state) or a light node (retrieving data live). It can be used by other processes as a gateway into the Ethereum network via JSON RPC endpoints exposed on top of HTTP, WebSocket and/or IPC transports. `geth --help` and the [CLI page](https://geth.ethereum.org/docs/interface/command-line-options) for command line options. | 40 | `clef` | Stand-alone signing tool, which can be used as a backend signer for `geth`. | 41 | `devp2p` | Utilities to interact with nodes on the networking layer, without running a full blockchain. | 42 | `abigen` | Source code generator to convert Ethereum contract definitions into easy to use, compile-time type-safe Go packages. It operates on plain [Ethereum contract ABIs](https://docs.soliditylang.org/en/develop/abi-spec.html) with expanded functionality if the contract bytecode is also available. However, it also accepts Solidity source files, making development much more streamlined. Please see our [Native DApps](https://geth.ethereum.org/docs/dapp/native-bindings) page for details. | 43 | `bootnode` | Stripped down version of our Ethereum client implementation that only takes part in the network node discovery protocol, but does not run any of the higher level application protocols. It can be used as a lightweight bootstrap node to aid in finding peers in private networks. | 44 | `evm` | Developer utility version of the EVM (Ethereum Virtual Machine) that is capable of running bytecode snippets within a configurable environment and execution mode. Its purpose is to allow isolated, fine-grained debugging of EVM opcodes (e.g. `evm --code 60ff60ff --debug run`). | 45 | `rlpdump` | Developer utility tool to convert binary RLP ([Recursive Length Prefix](https://eth.wiki/en/fundamentals/rlp)) dumps (data encoding used by the Ethereum protocol both network as well as consensus wise) to user-friendlier hierarchical representation (e.g. `rlpdump --hex CE0183FFFFFFC4C304050583616263`). | 46 | `puppeth` | a CLI wizard that aids in creating a new Ethereum network. | 47 48 ## Running `geth` 49 50 Going through all the possible command line flags is out of scope here (please consult our 51 [CLI Wiki page](https://geth.ethereum.org/docs/interface/command-line-options)), 52 but we've enumerated a few common parameter combos to get you up to speed quickly 53 on how you can run your own `geth` instance. 54 55 ### Hardware Requirements 56 57 Minimum: 58 59 * CPU with 2+ cores 60 * 4GB RAM 61 * 1TB free storage space to sync the Mainnet 62 * 8 MBit/sec download Internet service 63 64 Recommended: 65 66 * Fast CPU with 4+ cores 67 * 16GB+ RAM 68 * High Performance SSD with at least 1TB free space 69 * 25+ MBit/sec download Internet service 70 71 ### Full node on the main Ethereum network 72 73 By far the most common scenario is people wanting to simply interact with the Ethereum 74 network: create accounts; transfer funds; deploy and interact with contracts. For this 75 particular use-case the user doesn't care about years-old historical data, so we can 76 sync quickly to the current state of the network. To do so: 77 78 ```shell 79 $ geth console 80 ``` 81 82 This command will: 83 * Start `geth` in snap sync mode (default, can be changed with the `--syncmode` flag), 84 causing it to download more data in exchange for avoiding processing the entire history 85 of the Ethereum network, which is very CPU intensive. 86 * Start up `geth`'s built-in interactive [JavaScript console](https://geth.ethereum.org/docs/interface/javascript-console), 87 (via the trailing `console` subcommand) through which you can interact using [`web3` methods](https://github.com/ChainSafe/web3.js/blob/0.20.7/DOCUMENTATION.md) 88 (note: the `web3` version bundled within `geth` is very old, and not up to date with official docs), 89 as well as `geth`'s own [management APIs](https://geth.ethereum.org/docs/rpc/server). 90 This tool is optional and if you leave it out you can always attach to an already running 91 `geth` instance with `geth attach`. 92 93 ### A Full node on the Görli test network 94 95 Transitioning towards developers, if you'd like to play around with creating Ethereum 96 contracts, you almost certainly would like to do that without any real money involved until 97 you get the hang of the entire system. In other words, instead of attaching to the main 98 network, you want to join the **test** network with your node, which is fully equivalent to 99 the main network, but with play-Ether only. 100 101 ```shell 102 $ geth --goerli console 103 ``` 104 105 The `console` subcommand has the exact same meaning as above and they are equally 106 useful on the testnet too. Please, see above for their explanations if you've skipped here. 107 108 Specifying the `--goerli` flag, however, will reconfigure your `geth` instance a bit: 109 110 * Instead of connecting the main Ethereum network, the client will connect to the Görli 111 test network, which uses different P2P bootnodes, different network IDs and genesis 112 states. 113 * Instead of using the default data directory (`~/.ethereum` on Linux for example), `geth` 114 will nest itself one level deeper into a `goerli` subfolder (`~/.ethereum/goerli` on 115 Linux). Note, on OSX and Linux this also means that attaching to a running testnet node 116 requires the use of a custom endpoint since `geth attach` will try to attach to a 117 production node endpoint by default, e.g., 118 `geth attach <datadir>/goerli/geth.ipc`. Windows users are not affected by 119 this. 120 121 *Note: Although there are some internal protective measures to prevent transactions from 122 crossing over between the main network and test network, you should make sure to always 123 use separate accounts for play-money and real-money. Unless you manually move 124 accounts, `geth` will by default correctly separate the two networks and will not make any 125 accounts available between them.* 126 127 ### Full node on the Rinkeby test network 128 129 Go Ethereum also supports connecting to the older proof-of-authority based test network 130 called [*Rinkeby*](https://www.rinkeby.io) which is operated by members of the community. 131 132 ```shell 133 $ geth --rinkeby console 134 ``` 135 136 ### Full node on the Ropsten test network 137 138 In addition to Görli and Rinkeby, Geth also supports the ancient Ropsten testnet. The 139 Ropsten test network is based on the Ethash proof-of-work consensus algorithm. As such, 140 it has certain extra overhead and is more susceptible to reorganization attacks due to the 141 network's low difficulty/security. 142 143 ```shell 144 $ geth --ropsten console 145 ``` 146 147 *Note: Older Geth configurations store the Ropsten database in the `testnet` subdirectory.* 148 149 ### Configuration 150 151 As an alternative to passing the numerous flags to the `geth` binary, you can also pass a 152 configuration file via: 153 154 ```shell 155 $ geth --config /path/to/your_config.toml 156 ``` 157 158 To get an idea how the file should look like you can use the `dumpconfig` subcommand to 159 export your existing configuration: 160 161 ```shell 162 $ geth --your-favourite-flags dumpconfig 163 ``` 164 165 *Note: This works only with `geth` v1.6.0 and above.* 166 167 #### Docker quick start 168 169 One of the quickest ways to get Ethereum up and running on your machine is by using 170 Docker: 171 172 ```shell 173 docker run -d --name ethereum-node -v /Users/alice/ethereum:/root \ 174 -p 8545:8545 -p 30303:30303 \ 175 ethereum/client-go 176 ``` 177 178 This will start `geth` in snap-sync mode with a DB memory allowance of 1GB just as the 179 above command does. It will also create a persistent volume in your home directory for 180 saving your blockchain as well as map the default ports. There is also an `alpine` tag 181 available for a slim version of the image. 182 183 Do not forget `--http.addr 0.0.0.0`, if you want to access RPC from other containers 184 and/or hosts. By default, `geth` binds to the local interface and RPC endpoints are not 185 accessible from the outside. 186 187 ### Programmatically interfacing `geth` nodes 188 189 As a developer, sooner rather than later you'll want to start interacting with `geth` and the 190 Ethereum network via your own programs and not manually through the console. To aid 191 this, `geth` has built-in support for a JSON-RPC based APIs ([standard APIs](https://eth.wiki/json-rpc/API) 192 and [`geth` specific APIs](https://geth.ethereum.org/docs/rpc/server)). 193 These can be exposed via HTTP, WebSockets and IPC (UNIX sockets on UNIX based 194 platforms, and named pipes on Windows). 195 196 The IPC interface is enabled by default and exposes all the APIs supported by `geth`, 197 whereas the HTTP and WS interfaces need to manually be enabled and only expose a 198 subset of APIs due to security reasons. These can be turned on/off and configured as 199 you'd expect. 200 201 HTTP based JSON-RPC API options: 202 203 * `--http` Enable the HTTP-RPC server 204 * `--http.addr` HTTP-RPC server listening interface (default: `localhost`) 205 * `--http.port` HTTP-RPC server listening port (default: `8545`) 206 * `--http.api` API's offered over the HTTP-RPC interface (default: `eth,net,web3`) 207 * `--http.corsdomain` Comma separated list of domains from which to accept cross origin requests (browser enforced) 208 * `--ws` Enable the WS-RPC server 209 * `--ws.addr` WS-RPC server listening interface (default: `localhost`) 210 * `--ws.port` WS-RPC server listening port (default: `8546`) 211 * `--ws.api` API's offered over the WS-RPC interface (default: `eth,net,web3`) 212 * `--ws.origins` Origins from which to accept websockets requests 213 * `--ipcdisable` Disable the IPC-RPC server 214 * `--ipcapi` API's offered over the IPC-RPC interface (default: `admin,debug,eth,miner,net,personal,shh,txpool,web3`) 215 * `--ipcpath` Filename for IPC socket/pipe within the datadir (explicit paths escape it) 216 217 You'll need to use your own programming environments' capabilities (libraries, tools, etc) to 218 connect via HTTP, WS or IPC to a `geth` node configured with the above flags and you'll 219 need to speak [JSON-RPC](https://www.jsonrpc.org/specification) on all transports. You 220 can reuse the same connection for multiple requests! 221 222 **Note: Please understand the security implications of opening up an HTTP/WS based 223 transport before doing so! Hackers on the internet are actively trying to subvert 224 Ethereum nodes with exposed APIs! Further, all browser tabs can access locally 225 running web servers, so malicious web pages could try to subvert locally available 226 APIs!** 227 228 ### Operating a private network 229 230 Maintaining your own private network is more involved as a lot of configurations taken for 231 granted in the official networks need to be manually set up. 232 233 #### Defining the private genesis state 234 235 First, you'll need to create the genesis state of your networks, which all nodes need to be 236 aware of and agree upon. This consists of a small JSON file (e.g. call it `genesis.json`): 237 238 ```json 239 { 240 "config": { 241 "chainId": <arbitrary positive integer>, 242 "homesteadBlock": 0, 243 "eip150Block": 0, 244 "eip155Block": 0, 245 "eip158Block": 0, 246 "byzantiumBlock": 0, 247 "constantinopleBlock": 0, 248 "petersburgBlock": 0, 249 "istanbulBlock": 0, 250 "berlinBlock": 0, 251 "londonBlock": 0 252 }, 253 "alloc": {}, 254 "coinbase": "0x0000000000000000000000000000000000000000", 255 "difficulty": "0x20000", 256 "extraData": "", 257 "gasLimit": "0x2fefd8", 258 "nonce": "0x0000000000000042", 259 "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000", 260 "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000", 261 "timestamp": "0x00" 262 } 263 ``` 264 265 The above fields should be fine for most purposes, although we'd recommend changing 266 the `nonce` to some random value so you prevent unknown remote nodes from being able 267 to connect to you. If you'd like to pre-fund some accounts for easier testing, create 268 the accounts and populate the `alloc` field with their addresses. 269 270 ```json 271 "alloc": { 272 "0x0000000000000000000000000000000000000001": { 273 "balance": "111111111" 274 }, 275 "0x0000000000000000000000000000000000000002": { 276 "balance": "222222222" 277 } 278 } 279 ``` 280 281 With the genesis state defined in the above JSON file, you'll need to initialize **every** 282 `geth` node with it prior to starting it up to ensure all blockchain parameters are correctly 283 set: 284 285 ```shell 286 $ geth init path/to/genesis.json 287 ``` 288 289 #### Creating the rendezvous point 290 291 With all nodes that you want to run initialized to the desired genesis state, you'll need to 292 start a bootstrap node that others can use to find each other in your network and/or over 293 the internet. The clean way is to configure and run a dedicated bootnode: 294 295 ```shell 296 $ bootnode --genkey=boot.key 297 $ bootnode --nodekey=boot.key 298 ``` 299 300 With the bootnode online, it will display an [`enode` URL](https://eth.wiki/en/fundamentals/enode-url-format) 301 that other nodes can use to connect to it and exchange peer information. Make sure to 302 replace the displayed IP address information (most probably `[::]`) with your externally 303 accessible IP to get the actual `enode` URL. 304 305 *Note: You could also use a full-fledged `geth` node as a bootnode, but it's the less 306 recommended way.* 307 308 #### Starting up your member nodes 309 310 With the bootnode operational and externally reachable (you can try 311 `telnet <ip> <port>` to ensure it's indeed reachable), start every subsequent `geth` 312 node pointed to the bootnode for peer discovery via the `--bootnodes` flag. It will 313 probably also be desirable to keep the data directory of your private network separated, so 314 do also specify a custom `--datadir` flag. 315 316 ```shell 317 $ geth --datadir=path/to/custom/data/folder --bootnodes=<bootnode-enode-url-from-above> 318 ``` 319 320 *Note: Since your network will be completely cut off from the main and test networks, you'll 321 also need to configure a miner to process transactions and create new blocks for you.* 322 323 #### Running a private miner 324 325 Mining on the public Ethereum network is a complex task as it's only feasible using GPUs, 326 requiring an OpenCL or CUDA enabled `ethminer` instance. For information on such a 327 setup, please consult the [EtherMining subreddit](https://www.reddit.com/r/EtherMining/) 328 and the [ethminer](https://github.com/ethereum-mining/ethminer) repository. 329 330 In a private network setting, however a single CPU miner instance is more than enough for 331 practical purposes as it can produce a stable stream of blocks at the correct intervals 332 without needing heavy resources (consider running on a single thread, no need for multiple 333 ones either). To start a `geth` instance for mining, run it with all your usual flags, extended 334 by: 335 336 ```shell 337 $ geth <usual-flags> --mine --miner.threads=1 --miner.etherbase=0x0000000000000000000000000000000000000000 338 ``` 339 340 Which will start mining blocks and transactions on a single CPU thread, crediting all 341 proceedings to the account specified by `--miner.etherbase`. You can further tune the mining 342 by changing the default gas limit blocks converge to (`--miner.targetgaslimit`) and the price 343 transactions are accepted at (`--miner.gasprice`). 344 345 ## Contribution 346 347 Thank you for considering to help out with the source code! We welcome contributions 348 from anyone on the internet, and are grateful for even the smallest of fixes! 349 350 If you'd like to contribute to go-ethereum, please fork, fix, commit and send a pull request 351 for the maintainers to review and merge into the main code base. If you wish to submit 352 more complex changes though, please check up with the core devs first on [our Discord Server](https://discord.gg/invite/nthXNEv) 353 to ensure those changes are in line with the general philosophy of the project and/or get 354 some early feedback which can make both your efforts much lighter as well as our review 355 and merge procedures quick and simple. 356 357 Please make sure your contributions adhere to our coding guidelines: 358 359 * Code must adhere to the official Go [formatting](https://golang.org/doc/effective_go.html#formatting) 360 guidelines (i.e. uses [gofmt](https://golang.org/cmd/gofmt/)). 361 * Code must be documented adhering to the official Go [commentary](https://golang.org/doc/effective_go.html#commentary) 362 guidelines. 363 * Pull requests need to be based on and opened against the `master` branch. 364 * Commit messages should be prefixed with the package(s) they modify. 365 * E.g. "eth, rpc: make trace configs optional" 366 367 Please see the [Developers' Guide](https://geth.ethereum.org/docs/developers/devguide) 368 for more details on configuring your environment, managing project dependencies, and 369 testing procedures. 370 371 ## License 372 373 The go-ethereum library (i.e. all code outside of the `cmd` directory) is licensed under the 374 [GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.en.html), 375 also included in our repository in the `COPYING.LESSER` file. 376 377 The go-ethereum binaries (i.e. all code inside of the `cmd` directory) is licensed under the 378 [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), also 379 included in our repository in the `COPYING` file.