operation.md
1 # Introduction 2 3 This document describes how to start your Aeternity node installed using a release binary, verify that it mines and verify that it joined the configured public network of nodes (e.g. testnet). 4 5 The instructions below assume that: 6 7 * The node is deployed in directory `~/aeternity/node`; 8 * beneficiary account is set under `mining` > `beneficiary` in the config (see [configuration documentation](configuration.md)); 9 * No custom peers are specified under the `peers:` key in the config. If the `peers:` key is undefined, the *testnet* or *mainnet* seed peers (built-in in the package source) are used. 10 * The external HTTP endpoint of the user API of the node can be contacted at 127.0.0.1 port 3013. 11 * The location of the keys is set under `keys` > `dir` in the config (see [configuration documentation](configuration.md)). 12 13 If any of the assumptions does not hold, you need to amend the instructions accordingly. 14 15 ## Start the node 16 17 It is recommended that the node has at least 4 GB of memory available. 18 19 When it starts, the node checks the maximum number of open files (`ulimit -n`) and warns if below the recommended limit: proper max number of open files is essential to managing network connections and you should make sure you configure it in the session where you start the node. 20 21 Start the node: 22 ```bash 23 cd ~/aeternity/node 24 bin/aeternity start 25 ``` 26 27 (You can stop the node by running `bin/aeternity stop` from the same directory.) 28 29 Verify the node is up, by inspecting the current top of the blockchain as seen by the node: 30 ```bash 31 curl http://127.0.0.1:3013/v3/headers/top 32 ``` 33 34 If the node is unresponsive, inspect the `log` directory for errors. 35 36 Back up the peer key pair: 37 ```bash 38 cp -pr ~/aeternity/node/data/aecore/keys ~/my_aeternity_keys 39 ``` 40 41 ## Mainnet connection 42 43 To verify that node is connected to the mainnet, your node should see the same longest blockchain as the mainnet. 44 45 Inspect the current top of the blockchain as seen by the mainnet: 46 ```bash 47 curl https://mainnet.aeternity.io/v3/headers/top 48 ``` 49 50 Inspect the current top of the blockchain as seen by your node: 51 ```bash 52 curl http://127.0.0.1:3013/v3/headers/top 53 ``` 54 55 Verify that the height is the same; it may take a few minutes for your node to catch up with the mainnet blockchain. 56 57 ## Mining 58 59 To verify that node mines, inspect the mining log file of the node: 60 ```bash 61 less ~/aeternity/node/log/aeternity_mining.log 62 ``` 63 64 If the node is mining, you shall read log entries like the following: 65 ``` 66 ... Creating key block candidate on the top 67 ... Created key block candidate ... 68 ... Starting miner ... 69 ... Starting miner ... 70 ``` 71 72 If the node successfully mines a block, you shall read log entries like the following: 73 ``` 74 ... Block mined: Height = 1; Hash = ... 75 ``` 76 77 ## Mainnet mining 78 79 After the node is successfully connected to the mainnet, you could verify that it is mining on the same chain as the rest of the network. 80 You can validate it observing the `hash` of the `/headers/top` of the remote nodes: 81 ```bash 82 $ curl https://mainnet.aeternity.io/v3/headers/top 83 {"hash":"mh_2bZx1kGy5uqJRDzDQ8zyJwrQgeDah5k36u2AtHcUE3tSTJ9QyY","height":935925,..., 84 "prev_key_hash":"kh_26W973ssbCk6kaNdhMpwqA5xtyHF5DD7VxKqUZiTRcQz2BSbv4",...} 85 ``` 86 87 This is the hash of the block being at the top of the chain of the node and the 88 previous key hash should be same as the hash in `prev_key_hash` of the block 89 you're currently mining: 90 91 ```bash 92 $ curl http://127.0.0.1:3013/v3/key-blocks/pending 93 {...,"height":..., "prev_key_hash":"kh_26W973ssbCk6kaNdhMpwqA5xtyHF5DD7VxKqUZiTRcQz2BSbv4", ...} 94 ``` 95 96 Height would be +1 of what is in the `/headers/top` of the remote node but this is not as strong guarantee as the `prev_key_hash`. 97 98 99 100 ## Maintenance mode 101 102 It is possible to start the node in "maintenance mode", where mining, sync and HTTP 103 endpoints are disabled. To do so, start the node with `AE__SYSTEM__MAINTENANCE_MODE=true`. 104 This can be useful when debugging or performing maintenance tasks on the system. 105 106 ## Offline mode 107 108 It is possible to start the node in "offline mode", where mining and sync 109 endpoints are disabled. To do so, start the node with `AE__SYSTEM__OFFLINE_MODE=true`. 110 This can be useful when debugging or performing rosetta-cli testing on the system.