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>`.