github.com/nspcc-dev/neo-go@v0.105.2-0.20240517133400-6be757af3eba/docs/consensus.md (about) 1 # NeoGo consensus node 2 3 NeoGo node can act as a consensus node. A consensus node differs from a regular 4 one in that it participates in block acceptance process using dBFT 5 protocol. Any committee node can also be elected as a CN; therefore, they're 6 expected to follow the same setup process as CNs (to be ready to become CNs 7 if/when they're elected). 8 9 While regular nodes on Neo network don't need any special keys, CNs always have 10 one used to sign dBFT messages and blocks. So, the main difference between 11 a regular node and a consensus/committee node is that it should be configured to 12 use some key from some wallet. 13 14 ## Running a CN on public networks 15 16 ### Hardware requirements 17 18 While NeoGo can be very conservative with its resource consumption, public 19 network CN provides some service to the general audience and thus should have 20 enough hardware resources to do its job reliably. We recommend amd64 machine 21 with at least two cores, 8+ GB of memory and 64 GB SSD (disk space 22 requirements depend on actual chain height and 23 KeepOnlyLatestState/RemoveUntraceableBlocks settings, 64 GB is considered to 24 be enough for the first year of blockchain). 25 26 ### OS requirements 27 28 NeoGo is a single binary that can be run on any modern GNU/Linux 29 distribution. We recommend using major well-supported OSes like CentOS, Debian 30 or Ubuntu. Make sure they're updated with the latest security patches. 31 32 No additional packages are needed for NeoGo CN. 33 34 ### Installation 35 36 Download NeoGo binary [from 37 Github](https://github.com/nspcc-dev/neo-go/releases) or use [Docker 38 image](https://hub.docker.com/r/nspccdev/neo-go). It has everything included, 39 no additional plugins needed. 40 41 Take an appropriate (mainnet/testnet) configuration [from the 42 repository](https://github.com/nspcc-dev/neo-go/tree/master/config) and save 43 it in some directory (we'll assume that it's available in the same directory as 44 neo-go binary). 45 46 ### Configuration and execution 47 48 Add the following subsection to `ApplicationConfiguration` section of your 49 configuration file (`protocol.mainnet.yml` or `protocol.testnet.yml`): 50 ``` 51 Consensus: 52 Enabled: true 53 UnlockWallet: 54 Path: "wallet.json" 55 Password: "welcometotherealworld" 56 ``` 57 where `wallet.json` is a path to your NEP-6 wallet and `welcometotherealworld` 58 is a password to your CN key. Run the node in a regular way after that: 59 60 ``` 61 $ neo-go node --mainnet --config-path ./ 62 ``` 63 where `--mainnet` is your network (can be `--testnet` for testnet) and 64 `--config-path` is a path to the configuration file directory. If the node starts 65 fine, it'll be logging events like synchronized blocks. The node doesn't have 66 any interactive CLI, it only outputs logs so you can wrap this command in a 67 systemd service file to run automatically on system startup. 68 69 Notice that the default configuration has RPC and Prometheus services enabled. 70 You can turn them off for security purposes or restrict access to them with a 71 firewall. Carefully review all other configuration options to see if they meet 72 your expectations. Details on various configuration options are provided in the 73 [node configuration documentation](node-configuration.md), CLI commands are 74 provided in the [CLI documentation](cli.md). 75 76 Consensus service can also run in watch-only mode when the node will 77 receive/process/log dBFT messages generated by other nodes, but won't be able 78 to generate any. It's mostly useful for debugging/monitoring. To enable this 79 mode just drop the `UnlockWallet` section from the configuration like this: 80 ``` 81 Consensus: 82 Enabled: true 83 ``` 84 85 ### Registration 86 87 To register as a candidate, use neo-go as CLI command with an external RPC 88 server for it to connect to (for chain data and transaction submission). You 89 can use any public RPC server or an RPC server of your own like the node 90 started at the previous step. We'll assume that you run the next command on 91 the same node in default configuration with RPC interface available at port 92 10332. 93 94 Candidate registration is performed via NEO contract invocation that costs 95 1000 GAS, so your account must have enough of it to pay. You need to provide 96 your wallet and address to neo-go command: 97 ``` 98 $ neo-go wallet candidate register -a NiKEkwz6i9q6gqfCizztDoHQh9r9BtdCNa -w wallet.json -r http://localhost:10332 99 ``` 100 where `NiKEkwz6i9q6gqfCizztDoHQh9r9BtdCNa` is your address, `wallet.json` is a 101 path to NEP-6 wallet file and `http://localhost:10332` is an RPC node to 102 use. 103 104 This command will create and send appropriate transaction to the network and 105 you should then wait for it to settle in a block. If all goes well, it'll end 106 with "HALT" state and your registration will be completed. You can use 107 `query tx` command to see transaction status or `query candidates` to see if 108 your candidate has been added. 109 110 ### Voting 111 112 After registration is completed, if you own some NEO, you can also vote for your 113 candidate to help it become a CN and receive additional voter GAS. To do that, 114 you need to know the public key of your candidate, which can either be seen in 115 `query candidates` command output or extracted from wallet `wallet dump-keys` 116 command: 117 118 ``` 119 $ neo-go wallet dump-keys -w wallet.json 120 NiKEkwz6i9q6gqfCizztDoHQh9r9BtdCNa (simple signature contract): 121 0363f6678ea4c59e292175c67e2b75c9ba7bb73e47cd97cdf5abaf45de157133f5 122 ``` 123 124 `0363f6678ea4c59e292175c67e2b75c9ba7bb73e47cd97cdf5abaf45de157133f5` is a 125 public key for `NiKEkwz6i9q6gqfCizztDoHQh9r9BtdCNa` address. To vote for it 126 use: 127 ``` 128 $ neo-go wallet candidate vote -a NiKEkwz6i9q6gqfCizztDoHQh9r9BtdCNa -w wallet.json -r http://localhost:10332 -c 0363f6678ea4c59e292175c67e2b75c9ba7bb73e47cd97cdf5abaf45de157133f5 129 130 ``` 131 where `NiKEkwz6i9q6gqfCizztDoHQh9r9BtdCNa` is the voter's address, `wallet.json` 132 is the NEP-6 wallet file path, `http://localhost:10332` is the RPC node address and 133 `0363f6678ea4c59e292175c67e2b75c9ba7bb73e47cd97cdf5abaf45de157133f5` is the 134 public key the voter votes for. This command also returns transaction hash and you 135 need to wait for this transaction to be accepted into one of subsequent blocks. 136 137 ## Private NeoGo network 138 ### Using existing Dockerfile 139 140 neo-go comes with two preconfigured private network setups, the first one has 141 four consensus nodes and the second one uses single node. Nodes are packed 142 into Docker containers and four-node setup shares a volume for chain data. 143 144 Four-node setup uses ports 20333-20336 for P2P communication and ports 145 30333-30336 for RPC (Prometheus monitoring is also available at ports 146 20001-20004). Single-node is on ports 20333/30333/20001 for 147 P2P/RPC/Prometheus. 148 149 NeoGo default privnet configuration is made to work with four-node consensus, 150 you have to modify it if you're to use single consensus node. 151 152 Node wallets are located in the `.docker/wallets` directory where 153 `wallet1_solo.json` is used for single-node setup and all others for 154 four-node setup. 155 156 #### Prerequisites 157 - `docker` of version >= 20.10.0 158 - `docker-compose` 159 - `go` compiler 160 161 #### Instructions 162 You can use an existing docker-compose file located in `.docker/docker-compose.yml`: 163 ```bash 164 make env_image # build image 165 make env_up # start containers, use "make env_single" for single CN 166 ``` 167 To monitor logs: 168 ```bash 169 docker-compose -f .docker/docker-compose.yml logs -f 170 ``` 171 172 To stop: 173 ```bash 174 make env_down 175 ``` 176 177 To remove old blockchain state: 178 ```bash 179 make env_clean 180 ``` 181 182 ### Start nodes manually 183 1. Create a separate config directory for every node and 184 place the corresponding config named `protocol.privnet.yml` there. 185 186 2. Edit configuration file for every node. 187 Examples can be found at `config/protocol.privnet.docker.one.yml` (`two`, `three` etc.). 188 1. Add `Consensus` section with `Enabled: true` field and an 189 `UnlockWallet` subsection with `Path` and `Password` strings for NEP-6 190 wallet path and the password for the account to be used for the 191 consensus node. 192 2. Make sure that your `MinPeers` setting is no more than 193 the number of nodes participating in consensus minus one. The 194 recommended setting is 2F in terms of BFT, that's the minimum number 195 the network can operate with (0 for a single node, 2 for 4 CNs, 4 for 7 196 CNs). 197 3. Set `Address`, `Port` and `RPC.Port` to the appropriate values. 198 They must differ between nodes. 199 4. If you start binary from the same directory, you will probably want to change 200 `DataDirectoryPath` from the `LevelDBOptions`. 201 202 3. Start all nodes with `neo-go node --config-path <dir-from-step-2>`.